Skip to main content
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.
Стандартные клиенты ClickHouse Connect используют HTTP-интерфейс. Это позволяет работать с HTTP-балансировщиками нагрузки, прокси и распространёнными корпоративными средствами управления сетью. ClickHouse Connect также поддерживает экспериментальный backend chDB, работающий in-process chDB.

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

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

Установка

Установите ClickHouse Connect из PyPI с помощью команды pip:
Дополнительные интеграции устанавливаются через extras:
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:
Кнопка подключения сервиса ClickHouse Cloud
Выберите HTTPS. Сведения о подключении будут показаны в примере команды curl.
Сведения о подключении к ClickHouse Cloud по HTTPS
Если вы используете самоуправляемый ClickHouse, сведения о подключении задаёт ваш администратор ClickHouse.

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

Ниже показаны два примера подключения к ClickHouse:
  • Подключение к серверу ClickHouse на localhost.
  • Подключение к сервису ClickHouse Cloud.

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

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

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

Взаимодействие с базой данных

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

Встроенный backend chDB

Экспериментальный backend chDB выполняет запросы ClickHouse внутри процесса Python без HTTP-сервера. Установите дополнительный модуль chdb, затем выберите backend через interface="chdb" или DSN chdb://:
База данных по умолчанию находится в памяти. Передайте path="/data/my_chdb" или используйте dsn="chdb:///data/my_chdb" для постоянного хранения. chDB поддерживает только один путь движка для каждого процесса. Async-клиент и внешние данные не поддерживаются.
Последнее изменение 14 августа 2026 г.