Введение

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

• Основные интерфейсы — синхронный Client и нативный AsyncClient на базе aiohttp в clickhouse_connect.driver. Пакет драйвера также предоставляет контексты запросов и вставки, вспомогательные средства для стриминга, поддержку DB-API и низкоуровневые HTTP-методы.
• Пакет clickhouse_connect.datatypes сериализует и десериализует типы ClickHouse, используя бинарный столбцовый формат ClickHouse Native.
• Необязательные расширения Cython в clickhouse_connect.driverc ускоряют типовые пути сериализации, преобразования и буферизации. На платформах, где эти расширения нельзя собрать, по-прежнему доступен вариант на pure Python.
• Пакет поставляется с информацией о типах PEP 561, поэтому последующие инструменты проверки типов учитывают аннотации для публичного интерфейса драйвера, DB-API и поверхностей SQLAlchemy.
• Диалект SQLAlchemy в clickhouse_connect.cc_sqlalchemy поддерживает SQLAlchemy Core, отражение схемы, специфичные для ClickHouse секции запросов и движки таблиц, а также миграции Alembic. Базовые операции чтения и вставки ORM работают, но диалект рассчитан на аналитические рабочие нагрузки, а не на полноценную ORM-модель unit-of-work.
• Основной драйвер и реализация ClickHouse Connect SQLAlchemy — предпочтительный способ подключения ClickHouse к Apache Superset. Используйте подключение к базе данных ClickHouse Connect или строку подключения диалекта SQLAlchemy clickhousedb.

Эта документация актуальна для clickhouse-connect 1.6.0. Если вы обновляетесь с версии 0.15.x или более ранней, см. руководство по миграции на 1.0.

Пакет включает скомпилированные wheel-пакеты там, где они доступны, и использует реализацию на чистом Python, если расширения Cython не удаётся собрать. PyArrow поддерживается для Python 3.10–3.14. Для Python 3.14 требуется PyArrow 22 или новее.

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

pip install clickhouse-connect

Дополнительные интеграции устанавливаются через extras:

pip install "clickhouse-connect[async]"      # Native asyncio client
pip install "clickhouse-connect[pandas]"     # Pandas
pip install "clickhouse-connect[arrow]"      # PyArrow
pip install "clickhouse-connect[polars]"     # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
pip install "clickhouse-connect[tzdata]"     # IANA time zones on minimal systems

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

• Выполните git clone репозитория GitHub.
• Перейдите в корневой каталог проекта и выполните pip install .. Система сборки автоматически устанавливает Cython для компиляции необязательных C-расширений.

Установленную версию можно посмотреть в clickhouse_connect.__version__.

Прежде чем сообщать о проблеме, обновите ClickHouse Connect до последнего релиза. Сообщать о проблемах следует в проекте GitHub. ClickHouse Connect ориентирован на активно поддерживаемые релизы ClickHouse на момент выхода каждого релиза драйвера. Он часто работает и с более старыми версиями сервера, но для более новых типов данных и возможностей протокола может потребоваться более новая версия сервера.

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

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

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

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

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

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

import clickhouse_connect

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

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)
# Output: [(2000, -50.9035)]

client.close()

Экспериментальный backend chDB выполняет запросы ClickHouse внутри процесса Python без HTTP-сервера. Установите дополнительный модуль chdb, затем выберите backend через interface="chdb" или DSN chdb://:

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT number FROM numbers(3)")
    print(result.result_rows)
    # Output: [(0,), (1,), (2,)]

База данных по умолчанию находится в памяти. Передайте path="/data/my_chdb" или используйте dsn="chdb:///data/my_chdb" для постоянного хранения. chDB поддерживает только один путь движка для каждого процесса. Async-клиент и внешние данные не поддерживаются.