Перейти к основному содержанию
Перейти к основному содержанию

Введение

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

  • Основной интерфейс — объект Client в пакете clickhouse_connect.driver. Этот базовый пакет также включает различные вспомогательные классы и утилитные функции, используемые для взаимодействия с сервером ClickHouse, а также реализации «контекстов» для продвинутого управления запросами вставки и выборки.
  • Пакет 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Платформа¹ClickHouseSQLAlchemy²Apache SupersetPandasPolars
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 также может работать как чистый 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 и PORTОбычно используется порт 8443 при использовании TLS или 8123 при отсутствии TLS.
DATABASE NAMEПо умолчанию существует база данных default; используйте имя базы данных, к которой вы хотите подключиться.
USERNAME и PASSWORDПо умолчанию имя пользователя — default. Используйте имя пользователя, соответствующее вашему сценарию.

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

Кнопка подключения сервиса ClickHouse Cloud

Выберите HTTPS. Параметры подключения отображаются в примере команды curl.

Параметры HTTPS-подключения ClickHouse Cloud

Если вы используете самостоятельное (self-managed) развертывание ClickHouse, параметры подключения задаются администратором ClickHouse.

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

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

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

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

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='ваш_пароль')

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

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

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

Для пакетной вставки данных используйте клиентский метод insert с двумерным массивом строк (записей) и значений:

row1 = [1000, 'Строковое значение 1000', 5.233]
row2 = [2000, 'Строковое значение 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)] \{#output-2000-509035}