- Основные интерфейсы — синхронный
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или строку подключения диалекта SQLAlchemyclickhousedb.
Стандартные клиенты 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 или новее.
Установка
- Выполните
git cloneрепозитория GitHub. - Перейдите в корневой каталог проекта и выполните
pip install .. Система сборки автоматически устанавливает Cython для компиляции необязательных C-расширений.
clickhouse_connect.__version__.
Политика поддержки
Базовое использование
Подготовьте сведения о подключении
Сведения о подключении для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud.
Выберите сервис и нажмите Connect:

curl.

Установление соединения
- Подключение к серверу ClickHouse на localhost.
- Подключение к сервису ClickHouse Cloud.
Используйте экземпляр клиента ClickHouse Connect для подключения к серверу ClickHouse на localhost:
Используйте экземпляр клиента ClickHouse Connect для подключения к сервису ClickHouse Cloud:
Взаимодействие с базой данных
command клиента:
insert с двумерным массивом строк и значений:
query клиента:
Встроенный backend chDB
chdb, затем выберите backend через interface="chdb" или DSN chdb://:
path="/data/my_chdb" или используйте dsn="chdb:///data/my_chdb" для постоянного хранения. chDB поддерживает только один путь движка для каждого процесса. Async-клиент и внешние данные не поддерживаются.