Введение

Набор проектов ClickHouse Connect для подключения Python к ClickHouse

ClickHouse Connect — это основной драйвер базы данных, обеспечивающий совместимость с широким спектром Python-приложений.

• Основной интерфейс — объект Client в пакете clickhouse_connect.driver. Этот базовый пакет также включает различные вспомогательные классы и служебные функции для взаимодействия с сервером ClickHouse, а также реализации “context” для расширенного управления запросами вставки и выборки.
• Пакет clickhouse_connect.datatypes предоставляет базовую реализацию и подклассы для всех неэкспериментальных типов данных ClickHouse. Его основная функция — сериализация и десериализация данных ClickHouse в бинарный столбцовый формат ClickHouse “Native”, который обеспечивает максимально эффективную передачу данных между ClickHouse и клиентскими приложениями.
• Классы Cython/C в пакете clickhouse_connect.cdriver оптимизируют некоторые из наиболее распространённых операций сериализации и десериализации, обеспечивая значительно более высокую производительность по сравнению с чистым Python.
• В пакете clickhouse_connect.cc_sqlalchemy есть диалект SQLAlchemy, построенный на основе пакетов datatypes и dbi. Эта реализация поддерживает возможности SQLAlchemy Core, включая запросы SELECT с JOIN (INNER, LEFT OUTER, FULL OUTER, CROSS), секции WHERE, ORDER BY, операции LIMIT/OFFSET, операции DISTINCT, операторы легковесного DELETE с условиями WHERE, отражение таблиц и базовые операции DDL (CREATE TABLE, CREATE/DROP DATABASE). Хотя она не поддерживает расширенные возможности ORM или DDL, она предоставляет надёжные возможности выполнения запросов, подходящие для большинства аналитических рабочих нагрузок в OLAP-ориентированной базе данных ClickHouse.
• Основной драйвер и реализация ClickHouse Connect SQLAlchemy являются предпочтительным способом подключения ClickHouse к Apache Superset. Используйте подключение к базе данных ClickHouse Connect или строку подключения диалекта SQLAlchemy clickhousedb.

Эта документация актуальна для версии clickhouse-connect 0.9.2.

Официальный Python-драйвер ClickHouse Connect использует HTTP-протокол для взаимодействия с сервером ClickHouse. Это обеспечивает поддержку HTTP-балансировщиков нагрузки и хорошо работает в корпоративных средах с межсетевыми экранами и прокси, но уступает нативному TCP-протоколу по степени сжатия и производительности, а также не поддерживает некоторые расширенные возможности, такие как отмена запроса. В некоторых сценариях стоит рассмотреть использование одного из Community Python drivers, которые используют нативный TCP-протокол.

​

Требования и совместимость

Python		Platform¹		ClickHouse		SQLAlchemy²		Apache Superset		Pandas		Polars
2.x, <3.9	❌	Linux (x86)	✅	<25.x³	🟡	<1.4.40	❌	<1.4	❌	≥1.5	✅	1.x	✅
3.9.x	✅	Linux (Aarch64)	✅	25.x³	🟡	≥1.4.40	✅	1.4.x	✅	2.x	✅
3.10.x	✅	macOS (x86)	✅	25.3.x (LTS)	✅	≥2.x	✅	1.5.x	✅
3.11.x	✅	macOS (ARM)	✅	25.6.x (Stable)	✅			2.0.x	✅
3.12.x	✅	Windows	✅	25.7.x (Stable)	✅			2.1.x	✅
3.13.x	✅			25.8.x (LTS)	✅			3.0.x	✅
				25.9.x (Stable)	✅

¹ClickHouse Connect был протестирован на перечисленных платформах. Кроме того, для всех архитектур, поддерживаемых отличным проектом cibuildwheel, собираются непроверенные бинарные wheel-пакеты (с оптимизацией на C). Наконец, поскольку ClickHouse Connect может работать и в режиме pure Python, установка из исходного кода должна работать в любой современной среде Python.

²Поддержка SQLAlchemy ограничена функциональностью Core (запросы, базовый DDL). Возможности ORM не поддерживаются. Подробности см. в документации SQLAlchemy Integration Support.

³ClickHouse Connect в целом хорошо работает и с версиями вне официально поддерживаемого диапазона.

​

Установка

Установите ClickHouse Connect из PyPI с помощью pip:

pip install clickhouse-connect

ClickHouse Connect также можно установить из исходного кода:

• выполните git clone репозитория на GitHub.
• (Необязательно) выполните pip install cython, чтобы собрать пакет и включить оптимизации C/Cython
• перейдите в корневой каталог проекта с помощью cd и выполните pip install .

​

Политика поддержки

Пожалуйста, обновите ClickHouse Connect до последней версии, прежде чем сообщать о каких-либо проблемах. О проблемах следует сообщать в репозиторий GitHub. Ожидается, что будущие релизы ClickHouse Connect будут совместимы с версиями ClickHouse, которые на момент релиза находятся на активной поддержке. Актуальный список версий сервера ClickHouse, находящихся на активной поддержке, можно найти здесь. Если вы не уверены, какую версию сервера ClickHouse использовать, ознакомьтесь с этим обсуждением здесь. Наша матрица CI тестирует две последние LTS-версии и три последние стабильные версии. Однако благодаря HTTP-протоколу и минимальному количеству ломающих изменений между релизами ClickHouse, ClickHouse Connect обычно хорошо работает и с версиями сервера за пределами официально поддерживаемого диапазона, хотя совместимость с некоторыми расширенными типами данных может различаться.

​

Базовое использование

​

Подготовьте сведения о подключении

Чтобы подключиться к ClickHouse по HTTP(S), вам понадобится следующая информация:

Параметр(ы)	Описание
HOST and PORT	Обычно используется порт 8443 при использовании TLS и 8123 без TLS.
DATABASE NAME	По умолчанию есть база данных default; используйте имя базы данных, к которой хотите подключиться.
USERNAME and PASSWORD	По умолчанию имя пользователя — default. Используйте имя пользователя, подходящее для вашего сценария использования.

Сведения о подключении для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите сервис и нажмите Connect:

Выберите HTTPS. Сведения о подключении будут показаны в примере команды curl.

Если вы используете самоуправляемый ClickHouse, сведения о подключении задаёт ваш администратор ClickHouse.

​

Установление соединения

Ниже показаны два примера подключения к ClickHouse:

• Подключение к серверу ClickHouse на localhost.
• Подключение к сервису ClickHouse Cloud.

​

Используйте экземпляр клиента ClickHouse Connect для подключения к серверу ClickHouse на localhost:

import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', username='default', password='password')

​

Используйте экземпляр клиента ClickHouse Connect для подключения к сервису ClickHouse Cloud:

Используйте сведения о подключении, полученные ранее. Для сервисов ClickHouse Cloud требуется TLS, поэтому используйте порт 8443.

import clickhouse_connect

client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')

​

Работа с базой данных

Чтобы выполнить команду ClickHouse SQL, используйте метод command клиента:

client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')

Чтобы вставить данные батчем, используйте метод insert клиента, передав двумерный массив строк и значений:

row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])

Чтобы получить данные с помощью ClickHouse SQL, используйте метод query клиента:

result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Вывод: [(2000, -50.9035)]