API драйвера ClickHouse Connect - ClickHouse Documentation

Передавайте именованные аргументы в фабрики client и методы со множеством необязательных параметров.Методы, не описанные здесь, не считаются частью API и могут быть удалены или изменены.

Инициализация клиента

Используйте clickhouse_connect.get_client, чтобы создать синхронный Client, или установите дополнительный пакет async и вызовите clickhouse_connect.get_async_client с await, чтобы создать нативный AsyncClient.

Аргументы подключения

Параметр	Тип	По умолчанию	Описание
`interface`	str	`"http"`	`"http"` или `"https"`. Синхронная фабрика также поддерживает экспериментальный бэкенд `"chdb"`.
`host`	str	`"localhost"`	Хост или IP-адрес сервера ClickHouse.
`port`	int или None	`8123` или `8443`	По умолчанию используется 8123 для HTTP и 8443 для HTTPS. Передача `None` означает использование значения по умолчанию.
`username`	str или None	`"default"`	Имя пользователя ClickHouse. Также принимаются псевдонимы `user` и `user_name`.
`password`	str	`""`	Пароль для `username`. Не сочетайте аутентификацию по имени пользователя и паролю с аутентификацией по токену.
`access_token`	str или None	`None`	JWT-токен доступа к ClickHouse Cloud. Взаимоисключает использование `token_provider` и аутентификации по имени пользователя и паролю.
`token_provider`	callable или None	`None`	Вызываемый объект, который предоставляет JWT при первоначальной аутентификации и после её отклонения. Асинхронный провайдер можно использовать с `get_async_client`.
`database`	str или None	По умолчанию для пользователя	База данных по умолчанию. При передаче `None` запрашивается база данных по умолчанию для пользователя на сервере.
`secure`	bool или str	`False`	Включает HTTPS/TLS. `interface="https"` также включает HTTPS; то же самое происходит при использовании порта 443 или 8443, если `interface` не задан.
`dsn`	str или None	`None`	URL подключения. Явные именованные аргументы имеют старшинство над значениями, разобранными из DSN. Используйте процентное кодирование для зарезервированных символов в учетных данных и именах баз данных.
`settings`	dict или None	`None`	Настройки ClickHouse, применяемые ко всем запросам, отправляемым клиентом.
`headers`	dict or None	`None`	HTTP-заголовки, применяемые ко всем запросам, включая инициализацию клиента. Пользовательские заголовки применяются после заголовков драйвера по умолчанию и могут их переопределять.
`compress`	bool or str	`True`	Включите сжатие или укажите `"lz4"`, `"zstd"`, `"br"` или `"gzip"`. См. раздел Сжатие.
`query_limit`	int	`0`	Ограничение числа строк по умолчанию, добавляемое к подходящим запросам. Ноль означает отсутствие ограничений. Для больших результатов используйте потоковую передачу вместо материализации всего в памяти.
`query_retries`	int	`2`	Количество повторных попыток при ошибках чтения, допускающих повтор. Команды и операции вставки обычно не повторяются, поскольку повторное выполнение может привести к дублированию побочных эффектов.
`connect_timeout`	int для синхронного клиента, float для async-клиента	`10`	Тайм-аут установления нового соединения в секундах. Время ожидания свободного слота в пуле соединений не учитывается. Async-клиент принимает дробные значения секунд.
`send_receive_timeout`	int для синхронного клиента, float для async-клиента	`300`	Тайм-аут чтения из сокета в секундах. Async-клиент принимает дробные значения секунд.
`client_name`	str или None	`None`	Префикс, добавляемый к HTTP User-Agent для идентификации в `system.query_log`.
`session_id`	str или None	Генерируется для синхронных клиентов	Явно заданный ID сеанса ClickHouse. У синхронных клиентов он генерируется по умолчанию; у async-клиентов — нет.
`autogenerate_session_id`	bool или None	Глобальная настройка для синхронных клиентов, `False` — для async-клиентов	Переопределяет автоматическую генерацию ID сеанса. Если состояние сеанса не требуется, отключите это для клиента, используемого несколькими параллельными операциями.
`autogenerate_query_id`	bool или None	Глобальная настройка, `True`	Переопределяет автоматическую генерацию Query id в формате UUID.
`http_proxy`	str или None	Переменная окружения/по умолчанию	Адрес HTTP-прокси для клиента.
`https_proxy`	str или None	Переменная окружения/по умолчанию	Адрес HTTPS-прокси для каждого клиента.
`pool_mgr`	`urllib3.PoolManager` или None	Общий для процесса	Пользовательский менеджер пула только для синхронного клиента.
`tz_source`	str или None	`"auto"`	Резервный источник часового пояса для столбцов без метаданных часового пояса: `"auto"`, `"server"` или `"local"`.
`tz_mode`	str или None	`"naive_utc"`	Политика представления результатов в UTC: `"naive_utc"`, `"aware"` или `"schema"`. См. Часовые пояса.
`show_clickhouse_errors`	bool, булева строка, `"scrub"` или None	`True`	Управляет `str(exc)` для ошибок сервера, транспортных ошибок и `StreamFailureError` в середине потока. `True` включает URL запроса и завершающую информацию о версии сервера. `"scrub"` сохраняет текст SQL-ошибки и символьное имя, но удаляет хост/URL и завершающую часть `(version ...)`. `False` возвращает общее сообщение (`code` по-прежнему задаётся для ошибок сервера). Булевы строки допустимы. Другие строки вызывают `ProgrammingError`. Для транспортных ошибок `__cause__` и трассировки стека по-прежнему содержат исходное транспортное исключение.
`proxy_path`	str	`""`	Префикс пути, добавляемый к URL сервера при маршрутизации через proxy.
`form_encode_query_params`	bool	`False`	Всегда помещать параметры запроса в тело HTTP-запроса в формате form-encoded. Крупные полезные нагрузки небинарных параметров автоматически переносятся туда, даже если это значение равно false.
`native_codec`	str или None	Глобальная настройка, `"python"`	Экспериментальный кодек для трафика в формате Native, управляемого клиентом: `"python"`, `"rust"` или `"rust_strict"`. Значения с Rust требуют wheel-пакета `clickhouse-connect-core`. См. Кодек на Rust.
`rename_response_column`	str или None	`None`	Стратегия переименования столбцов: `"remove_prefix"`, `"to_camelcase"`, `"to_camelcase_without_prefix"`, `"to_underscore"` или `"to_underscore_without_prefix"`.

И синхронные, и асинхронные HTTP-фабрики преобразуют строковые значения из параметров запроса DSN или generic_args для следующих параметров клиента: connect_timeout, send_receive_timeout, query_limit и query_retries приводятся к указанным выше числовым типам, а autogenerate_query_id, autogenerate_session_id и form_encode_query_params — к булевым значениям. Если строковое значение одного из этих параметров недопустимо, возникает исключение ProgrammingError. Асинхронная фабрика также принимает connector_limit=100, connector_limit_per_host=20 и keepalive_timeout=30.0 для настройки пула соединений aiohttp. Их можно передать как именованные аргументы, как параметры запроса DSN или через generic_args, который внутренне используется для connect_args в SQLAlchemy. Строковые значения этих параметров коннектора преобразуются в числовые типы, указанные в документации. Если строковое значение одного из этих параметров недопустимо, возникает исключение ProgrammingError. Явно заданные именованные аргументы со значением, отличным от None, имеют приоритет над generic_args, а те, в свою очередь, — над DSN. Параметр pool_mgr не поддерживается. Синхронный backend chDB принимает path и chdb_options; см. раздел Встроенный backend chDB.

Аргументы HTTPS/TLS

Параметр	Тип	По умолчанию	Описание
`verify`	bool or str	`True`	Проверяет сертификат сервера и имя хоста. `verify="proxy"` включает режим прокси TLS.
`ca_cert`	str or None	`None`	Путь к набору CA. Используйте `"certifi"`, чтобы выбрать набор, поставляемый с пакетом `certifi`.
`client_cert`	str or None	`None`	PEM-сертификат клиента, включая промежуточные сертификаты, если это требуется.
`client_cert_key`	str or None	`None`	Путь к закрытому ключу, если ключ не включён в `client_cert`.
`server_host_name`	str or None	`None`	Имя хоста TLS-сертификата/SNI, если оно отличается от `host`, например при использовании туннеля или частной конечной точки.
`tls_mode`	str or None	`None`	`"mutual"` использует аутентификацию ClickHouse по схеме взаимного TLS. `"proxy"` и `"strict"` передают сертификат на уровне TLS без включения заголовков аутентификации ClickHouse по сертификату. Значение по умолчанию `None` ведёт себя как `"mutual"`, если предоставлен сертификат клиента.

Аргумент settings

Наконец, аргумент settings для get_client используется для передачи серверу дополнительных настроек ClickHouse с каждым клиентским запросом. Обратите внимание, что в большинстве случаев пользователи с доступом readonly=1 не могут изменять настройки, передаваемые вместе с запросом, поэтому ClickHouse Connect отбрасывает такие настройки в итоговом запросе и записывает предупреждение в журнал. Следующие настройки применяются только к HTTP-запросам/сеансам, используемым ClickHouse Connect, и не документированы как общие настройки ClickHouse.

Setting	Описание
`buffer_size`	Размер буфера HTTP-ответа на стороне сервера в байтах.
`session_id`	Идентификатор сеанса, используемый для связывания связанных запросов. Требуется для временных таблиц и состояния сеанса.
`compress`	Указывает серверу сжимать HTTP-ответ. Обычно управляется параметром сжатия клиента.
`decompress`	Указывает серверу распаковывать тело запроса. Используется для предварительно сжатых raw-вставок.
`quota_key`	Ключ квоты, связанный с запросом.
`session_check`	Указывает серверу проверить существование сеанса.
`session_timeout`	Тайм-аут неактивности сеанса в секундах.
`wait_end_of_query`	Буферизует полный ответ на сервере. Клиент устанавливает этот параметр при необходимости для нестриминговой сводной информации.
`query_id`	Явный Query id для запроса.
`client_protocol_version`	Уровень возможностей клиентского протокола в native-формате. Обычно согласовывается автоматически.
`role`	Роль ClickHouse для использования в запросе/сеансе.

О других настройках ClickHouse, которые можно передавать с каждым запросом, см. в документации ClickHouse.

Примеры создания клиента

Без параметров клиент ClickHouse Connect подключится к HTTP-порту по умолчанию на localhost с пользователем по умолчанию default и без пароля:

import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)

Подключение к защищённому (HTTPS) внешнему серверу ClickHouse

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    secure=True,
    port=443,
    username="play",
    password="clickhouse",
)
print(client.command("SELECT timezone()"))

Подключение с идентификатором сеанса, а также с другими пользовательскими параметрами подключения и настройками ClickHouse.

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    username="play",
    password="clickhouse",
    port=443,
    secure=True,
    session_id="example_session_1",
    connect_timeout=15,
    database="github",
    settings={"distributed_ddl_task_timeout": 300},
)
print(client.database)
# Output: github

Встроенное backend-соединение chDB

Установите clickhouse-connect[chdb], чтобы использовать экспериментальное backend-соединение chDB, работающее в процессе приложения. Оно предоставляет синхронные методы клиента: запросы, вставка, стриминг и методы Arrow:

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT sum(number) FROM numbers(10)")
    print(result.first_row)
    # Output: (45,)

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

Жизненный цикл клиента и рекомендации

Создание клиента ClickHouse Connect — ресурсоемкая операция, включающая установление соединения, получение метаданных сервера и инициализацию настроек. Следуйте этим рекомендациям для оптимальной производительности:

Основные принципы

Повторно используйте клиенты: Создавайте клиенты один раз при запуске приложения и используйте их повторно в течение всего жизненного цикла приложения
Избегайте частого создания: Не создавайте новый клиент для каждого запроса или обращения
Корректно освобождайте ресурсы: Всегда закрывайте клиенты при завершении работы, чтобы освободить ресурсы пула соединений
По возможности используйте совместно: Один клиент может обрабатывать множество параллельных запросов через свой пул соединений (см. примечания о потоках ниже)

Основные рекомендации

Повторно используйте один экземпляр клиента:

import clickhouse_connect

# Create once at startup
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)

# Reuse for all queries
for i in range(1000):
    result = client.query("SELECT count() FROM users")

# Close on shutdown
client.close()

Избегайте повторного создания клиентов:

# BAD: Creates 1000 clients with expensive initialization overhead
for i in range(1000):
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    result = client.query("SELECT count() FROM users")
    client.close()

Многопоточные приложения

Экземпляры клиента НЕ являются потокобезопасными при использовании идентификаторов сеанса. По умолчанию клиентам назначается автоматически сгенерированный идентификатор сеанса. Параллельные запросы через один клиент в рамках одного сеанса приводят к ProgrammingError, если клиент обнаруживает их локальное пересечение. Состояние именованного сеанса и серверные проверки пересечения сеансов действуют только в пределах одного процесса сервера ClickHouse, поэтому фиксированный session_id не обеспечивает ни распределённого состояния, ни распределённого мьютекса в ClickHouse Cloud и других развертываниях с балансировкой нагрузки.

Чтобы безопасно использовать один клиент в нескольких потоках:

import clickhouse_connect
import threading

# Option 1: Disable sessions (recommended for shared clients)
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
    autogenerate_session_id=False,
)

def worker(thread_id):
    # All threads can now safely use the same client
    result = client.query(f"SELECT {thread_id}")
    print(f"Thread {thread_id}: {result.result_rows[0][0]}")

threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

client.close()

Альтернатива при использовании сеансов: Если вам нужны сеансы (например, для временных таблиц), создайте отдельный клиент для каждого потока:

def worker(thread_id):
    # Each thread gets its own client with isolated session
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory")
    # ... use temp table ...
    client.close()

Правильная очистка

Всегда закрывайте клиенты при завершении работы. Обратите внимание: client.close() освобождает клиент и закрывает HTTP-соединения из пула только в том случае, если клиент управляет собственным менеджером пула (например, если он создан с пользовательскими параметрами TLS/прокси). Для общего пула по умолчанию используйте client.close_connections(), чтобы принудительно очистить сокеты; в противном случае соединения будут автоматически освобождены по истечении периода бездействия и при завершении процесса.

client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)
try:
    result = client.query("SELECT 1")
finally:
    client.close()

Или используйте контекстный менеджер:

with clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
) as client:
    result = client.query("SELECT 1")

Когда использовать несколько клиентов

Несколько клиентов уместны в следующих случаях:

Разные серверы: один клиент на каждый сервер ClickHouse или кластер
Разные учетные данные: отдельные клиенты для разных пользователей или уровней доступа
Разные базы данных: когда нужно работать с несколькими базами данных
Изолированные сеансы: когда нужны отдельные сеансы для временных таблиц или настроек, специфичных для сеанса
Изоляция на уровне потоков: когда потокам нужны независимые сеансы (как показано выше)

Общие аргументы методов

В некоторых методах клиента используются один или оба стандартных именованных аргумента: parameters и settings. Они описаны ниже.

Аргумент `parameters`

Методы query* и command клиента ClickHouse Connect принимают необязательный именованный аргумент parameters, который используется для привязки выражений Python к выражению значения в ClickHouse. Доступны два типа привязки.

Привязка на стороне сервера

ClickHouse поддерживает привязку на стороне сервера для значений в запросе. Привязанное значение передаётся отдельно от запроса в виде HTTP-параметра. ClickHouse Connect использует этот режим, когда обнаруживает выражение в формате {<name>:<datatype>}. Передавайте значения в виде словаря Python. Имена параметров должны быть ASCII-именами ClickHouse BareWord. Драйвер принимает $ в начале, внутри или в конце имени, если сервер допускает его использование, например {$tenant_id:String}. Ключ словаря, который начинается и заканчивается символом $ и содержит буферное значение, например bytes, bytearray или memoryview, зарезервирован для соглашения ClickHouse Connect об использовании необработанных двоичных параметров. Если такой ключ используется для небинарного параметра с привязкой на стороне сервера, используйте для него только один заполнитель {name:Type}. Повторяющиеся имена $tag$ могут быть разобраны ClickHouse как маркеры heredoc. Используйте Python None для допускающих NULL значений. Вложенные значения None поддерживаются внутри параметров Array и Tuple, а также внутри литералов Map, когда dict_parameter_format имеет значение "map".

Привязка на стороне сервера со словарём Python, значением DateTime и строковым значением

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {
    "table": "my_table",
    "v1": my_date,
    "v2": "a string with a single quote'",
}
client.query(
    "SELECT * FROM {table:Identifier} "
    "WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
    parameters=parameters,
)

Это эквивалентно:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

Привязка на стороне сервера работает с запросами SELECT и операторами INSERT ... VALUES. Для вставки больших батчей обычных данных лучше использовать Client.insert.

Привязка на стороне клиента

ClickHouse Connect также поддерживает привязку параметров на стороне клиента, что дает больше гибкости при формировании шаблонизированных SQL-запросов. Для привязки на стороне клиента аргумент parameters должен быть словарём или последовательностью. При привязке на стороне клиента для подстановки параметров используется форматирование строк Python в стиле “printf”. Обратите внимание: в отличие от привязки на стороне сервера, привязка на стороне клиента не работает с идентификаторами баз данных, таблиц и столбцов, поскольку форматирование в стиле Python не различает разные типы строк, а для них требуется разное оформление (обратные кавычки или двойные кавычки для идентификаторов базы данных и одинарные кавычки для значений данных).

Пример с Python-словарём, значением DateTime и экранированием строк

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
    "SELECT * FROM my_table "
    "WHERE date >= %(v1)s AND string ILIKE %(v2)s",
    parameters=parameters,
)

В результате на сервере формируется следующий запрос:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

Пример с последовательностью Python Sequence (Tuple), Float64 и IPv4Address

import ipaddress

parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
    "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
    parameters=parameters,
)

В результате на сервере формируется следующий запрос:

SELECT *
FROM some_table
WHERE metric >= 35200.44
  AND ip_address = '68.61.4.254'

При привязке значения datetime без часового пояса интерпретируются как календарное время. Клиент форматирует datetime без часового пояса дословно. ClickHouse интерпретирует его в часовом поясе, объявленном в заполнителе на стороне сервера, например {dt:DateTime('Europe/Berlin')}, затем в session_timezone, если он задан, и наконец в часовом поясе сервера. datetime с часовым поясом преобразуется в часовой пояс, объявленный в заполнителе, если он указан, иначе — в часовой пояс сервера, полученный при подключении. Если настройка session_timezone отличается от полученного часового пояса сервера, укажите часовой пояс в заполнителе, чтобы сохранить нужный момент времени для значений с часовым поясом.Для временной совместимости с прежним преобразованием в локальный часовой пояс хоста задайте common.set_setting("naive_datetime_binding", "legacy") перед привязкой параметров. Чтобы сохранить момент времени, добавьте нужный tzinfo к значению datetime перед передачей его в качестве параметра. При вставке в столбцы DateTime или DateTime64 через client.insert значения datetime без часового пояса по умолчанию интерпретируются в локальном часовом поясе процесса. Задайте глобальную настройку naive_datetime_insert в значение "server", чтобы интерпретировать их как календарное время в часовом поясе столбца или в часовом поясе сервера, если у столбца он не задан. См. Объекты datetime без часового пояса.При нативной вставке в столбцы Date и Date32 используется календарная дата самого значения Python datetime, без преобразования часового пояса. Если одна и та же календарная дата нужна и для вставки, и для параметра запроса, явно передавайте value.date(). См. Значения Date и Date32.Для заполнителя {value:DateTime64(precision)} на стороне сервера объявленный тип автоматически сохраняет точность до долей секунды, в том числе внутри подсказок Array и Tuple.Привязка %s на стороне клиента не имеет объявленного типа. Оберните datetime в DT64Param, если его нужно выводить с точностью до долей секунды:

from datetime import datetime

from clickhouse_connect.driver.binding import DT64Param

query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)

Для обратной совместимости имя параметра в словаре, оканчивающееся на _64, также включает форматирование DateTime64, если точное имя с этим суффиксом отсутствует в запросе.Параметры datetime.time и datetime.timedelta форматируются как литерал [-]HH:MM:SS[.ffffff] для столбцов ClickHouse Time и Time64 в обоих стилях привязки и внутри значений Array и Tuple. Кавычки добавляет клиент, поэтому не заключайте заполнитель в кавычки в запросе. Значение timedelta может быть отрицательным и превышать 24 часа. Timedelta из pandas сохраняет наносекунды и форматирует дробную часть из девяти цифр для Time64(9). Информация о часовом поясе в значении time с часовым поясом игнорируется, поскольку тип ClickHouse Time не поддерживает часовые пояса.

аргумент settings

Все основные методы клиента ClickHouse Connect — “insert” и “select” — принимают необязательный именованный аргумент settings, который позволяет передавать пользовательские настройки сервера ClickHouse для данного SQL-оператора. Аргумент settings должен быть словарём. Каждый элемент должен содержать имя настройки ClickHouse и соответствующее ей значение. Обратите внимание, что при отправке на сервер в качестве параметров запроса значения будут преобразованы в строки. Как и в случае с настройками на уровне клиента, ClickHouse Connect отбрасывает любые настройки, которые сервер помечает как readonly=1, с соответствующим сообщением в журнале. Настройки, применимые только к запросам через HTTP-интерфейс ClickHouse, всегда допустимы. Эти настройки описаны в API get_client. Пример использования настроек ClickHouse:

settings = {
    "merge_tree_min_rows_for_concurrent_read": 65535,
    "session_id": "session_1234",
    "use_skip_indexes": False,
}
client.query(
    "SELECT event_type, sum(timeout) "
    "FROM event_errors WHERE event_time > '2022-08-01'",
    settings=settings,
)

Метод `command` клиента

Используйте Client.command для операторов, которые не возвращают табличный набор данных, или для запросов, которые возвращают одно примитивное значение или одну строку. В зависимости от ответа метод возвращает строку, целое число, последовательность строк или QuerySummary. Если чтение даёт пустой результирующий набор, возвращается пустая строка.

Параметр	Тип	По умолчанию	Описание
cmd	str	Required	Оператор ClickHouse SQL, который возвращает одно значение или одну строку значений.
parameters	dict or sequence	None	См. описание параметра parameters.
data	str or bytes	None	Необязательные данные, включаемые в команду как тело POST-запроса.
settings	dict	None	См. описание параметра settings.
use_database	bool	True	Использовать базу данных клиента (указанную при создании клиента). False означает, что команда будет использовать базу данных сервера ClickHouse по умолчанию для подключенного пользователя.
external_data	ExternalData	None	Объект `ExternalData`, содержащий файловые или бинарные данные для использования с запросом. См. Advanced Queries (External Data)
transport_settings	dict	None	Необязательный словарь HTTP-заголовков, который включается в этот запрос. Каждая пара ключ-значение добавляется как HTTP-заголовок (например, `{'X-Custom-Header': 'value'}`). Полезно для аутентификации через прокси, трассировки запросов или передачи заголовков, требуемых промежуточной инфраструктурой.

Примеры команд

DDL-операторы

import clickhouse_connect

client = clickhouse_connect.get_client()

# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
    "CREATE TABLE test_command "
    "(col_1 String, col_2 DateTime) "
    "ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())

# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
#     `col_1` String,
#     `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()

# Drop table
client.command("DROP TABLE test_command")

Простые запросы, возвращающие одиночные значения

import clickhouse_connect

client = clickhouse_connect.get_client()

# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)

# Server version
version = client.command("SELECT version()")
print(version)

Команды с параметрами

import clickhouse_connect

client = clickhouse_connect.get_client()

# Использование параметров на стороне клиента
table_name = "system"
result = client.command(
    "SELECT count() FROM system.tables WHERE database = %(db)s",
    parameters={"db": table_name}
)

# Использование параметров на стороне сервера
result = client.command(
    "SELECT count() FROM system.tables WHERE database = {db:String}",
    parameters={"db": "system"}
)

Команды с настройками

import clickhouse_connect

client = clickhouse_connect.get_client()

# Выполнение команды с определёнными настройками
result = client.command(
    "OPTIMIZE TABLE large_table FINAL",
    settings={"optimize_throw_if_noop": 1}
)

Метод `query` клиента `Client`

Client.query получает табличный набор данных в Native format ClickHouse и возвращает QueryResult. Полный результат материализуется при обращении к его свойству. Для результатов, которые не следует хранить в памяти, используйте стриминговый метод.

Если клиент обнаруживает в конце запроса LIMIT 0, он запрашивает метаданные столбцов в формате JSON. Если ответ содержит строки, клиент выбрасывает исключение clickhouse_connect.driver.exceptions.InternalError и не выполняет запрос повторно. Такое возможно с запросами UNION, EXCEPT или EXPLAIN, заканчивающимися на LIMIT 0.Для таких запросов используйте raw_query с выходным форматом, например fmt="JSON". Метод возвращает bytes, которые ваше приложение должно декодировать самостоятельно. Это поведение распространяется на синхронные и асинхронные HTTP-клиенты, а также на клиенты chDB.

Параметр	Тип	По умолчанию	Описание
`query`	str	Required	запрос к ClickHouse, который возвращает табличный результат, чаще всего `SELECT` или `DESCRIBE`. Может быть опущен, если передан через `context`.
`parameters`	dict or sequence	`None`	См. аргумент Parameters.
`settings`	dict	`None`	См. аргумент Settings.
`query_formats`	dict	`None`	Формат чтения по типу ClickHouse. См. Форматы чтения.
`column_formats`	dict	`None`	Формат чтения по столбцу результата, включая сопоставления форматов для типа Nested.
`encoding`	str	`None`	Кодирование столбцов String. По умолчанию используется UTF-8.
`use_none`	bool	`True`	Возвращает `None` для SQL NULL. Если указано false, возвращает значение NULL этого типа по умолчанию. Методы NumPy/Pandas выбирают значения по умолчанию с приоритетом производительности.
`column_oriented`	bool	`False`	Возвращает результат в виде столбцов, а не строк.
`use_numpy`	bool	`False`	Считывает совместимые столбцы результата в массивы NumPy внутри `QueryResult`. Если нужен результат в виде одной матрицы NumPy, предпочтительно использовать `query_np`.
`max_str_len`	int	`0`	При `use_numpy` использует Unicode dtype фиксированной ширины для столбцов String длиной до этого значения. Ноль использует массивы объектов.
`context`	`QueryContext`	`None`	Контекст запроса для повторного использования. Явно заданные аргументы метода переопределяют значения контекста.
`query_tz`	str or `tzinfo`	`None`	Часовой пояс, применяемый ко всем столбцам результата `DateTime` и `DateTime64`.
`column_tzs`	dict	`None`	Сопоставление часовых поясов для отдельных столбцов.
`external_data`	`ExternalData`	`None`	Внешний файл или бинарные данные. См. Внешние данные.
`transport_settings`	dict	`None`	HTTP-заголовки, добавляемые к этому запросу.
`tz_mode`	str	Client default	Переопределение обработки часовых поясов для отдельного запроса: `"naive_utc"`, `"aware"` или `"schema"`.

Примеры запросов

Простой запрос

import clickhouse_connect

client = clickhouse_connect.get_client()

# Simple SELECT query
result = client.query(
    "SELECT number, toString(number) AS label FROM numbers(3)"
)

# Access results as rows
for row in result.result_rows:
    print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')

# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']

Доступ к результатам запроса

import clickhouse_connect

client = clickhouse_connect.get_client()

result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]

# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]

# Named results (list of dictionaries)
for row_dict in result.named_results():
    print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}

# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}

# First row as tuple
print(result.first_row)
# Output: (0, '0')

Запрос с параметрами на стороне клиента

import clickhouse_connect

client = clickhouse_connect.get_client()

# Использование параметров словаря (в стиле printf)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)

# Использование параметров кортежа
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)

Запрос с параметрами на стороне сервера

import clickhouse_connect

client = clickhouse_connect.get_client()

# Привязка на стороне сервера (более безопасна, обеспечивает лучшую производительность для SELECT-запросов)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)

Запрос с настройками

import clickhouse_connect

client = clickhouse_connect.get_client()

# Передать настройки ClickHouse вместе с запросом
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)

Объект `QueryResult`

Базовый метод query возвращает объект QueryResult со следующими публичными свойствами:

result_rows — Матрица результатов, представленная в виде строк.
result_columns — Матрица результатов, представленная в виде столбцов.
result_set — result_rows или result_columns в зависимости от ориентации запроса.
column_names — Кортеж имен столбцов результата.
column_types — Кортеж объектов ClickHouseType.
row_count — Количество материализованных строк результата.
query_id — Query id, указанный или сгенерированный для этого запроса. Пустая строка означает, что он недоступен.
summary — Словарь, декодированный из заголовка ответа X-ClickHouse-Summary.
first_item — Первая строка в виде словаря или None для пустого результата.
first_row — Первая строка в виде последовательности или None для пустого результата.
column_block_stream, row_block_stream и rows_stream — Внутренние контексты потоков. Вместо них используйте соответствующие стриминговые методы клиента.

См. Стриминговые запросы, чтобы узнать о поддерживаемых API StreamContext.

Получение результатов запросов с помощью NumPy, Pandas или Arrow

ClickHouse Connect предоставляет специализированные методы запросов для форматов данных NumPy, Pandas и Arrow. Подробную информацию об использовании этих методов, включая примеры, возможности стриминга и расширенную обработку типов, см. в разделе Расширенное выполнение запросов (запросы NumPy, Pandas и Arrow).

Методы потокового выполнения запросов в клиенте

Для потоковой передачи больших результирующих наборов ClickHouse Connect предоставляет несколько методов. Подробности и примеры см. в разделе Расширенные запросы (потоковые запросы).

Метод клиента `insert`

Для типичного сценария вставки нескольких записей в ClickHouse предусмотрен метод Client.insert. Он принимает следующие параметры:

Parameter	Type	Default	Description
`table`	str	Обязательно	Целевая таблица. Допускается имя с указанием базы данных. Может быть опущено, если задана через `context`.
`data`	Sequence of Sequences	Обязательно	Матрица данных в строковом или столбцовом формате. Может быть передана позже через `InsertContext`.
`column_names`	str or Sequence[str]	`"*"`	Упорядоченные столбцы. `"*"` запускает запрос метаданных для определения всех столбцов, в которые можно выполнять вставку.
`database`	str or None	База данных клиента	Целевая база данных, если `table` указана без базы данных.
`column_types`	Sequence[`ClickHouseType`]	`None`	Явно заданные типы столбцов. При указании позволяет избежать запроса метаданных.
`column_type_names`	Sequence[str]	`None`	Явно заданные имена типов ClickHouse. Альтернатива `column_types`.
`column_oriented`	bool	`False`	Интерпретировать `data` как столбцы, а не как строки.
`settings`	dict	`None`	См. аргумент Settings.
`context`	`InsertContext`	`None`	Повторно используемый контекст вставки. См. InsertContexts.
`transport_settings`	dict	`None`	HTTP-заголовки, добавляемые к этому запросу.

Этот метод возвращает QuerySummary. Его словарь summary содержит значения, сообщаемые сервером. written_rows — это удобное свойство, а written_bytes() и query_id() возвращают соответствующие значения. При ошибке вставки будет вызвано исключение. Описание специализированных методов вставки, работающих с Pandas DataFrames, PyArrow Tables и DataFrames на базе Arrow, см. в разделе Расширенная вставка (Специализированные методы вставки).

Массив NumPy является допустимым Sequence of Sequences и может использоваться как аргумент data для основного метода insert, поэтому специализированный метод не требуется.

Примеры

В примерах ниже предполагается наличие таблицы users со схемой (id UInt32, name String, age UInt8).

Базовая построчная вставка

import clickhouse_connect

client = clickhouse_connect.get_client()

# Row-oriented data: each inner list is a row
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert("users", data, column_names=["id", "name", "age"])

Вставка в столбцовом формате

import clickhouse_connect

client = clickhouse_connect.get_client()

# Column-oriented data: each inner list is a column
data = [
    [13, 79],  # id column
    ["user_1", "user_2"],  # name column
    [25, 30],  # age column
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)

Вставка с явным указанием типов столбцов

import clickhouse_connect

client = clickhouse_connect.get_client()

# Useful when you want to avoid a DESCRIBE query to the server
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)

Вставка в определённую базу данных

import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

# Insert into a table in a specific database
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)

Вставка из файлов

Чтобы напрямую вставлять данные из файлов в таблицы ClickHouse, см. Расширенная вставка (вставка из файлов).

Raw API

Для продвинутых сценариев, требующих прямого доступа к HTTP-интерфейсам ClickHouse без преобразования типов, см. Расширенное использование (Raw API).

Python DB-API 2.0

Модуль clickhouse_connect.dbapi реализует интерфейсы connection и cursor, определённые в PEP 249. Он объявляет уровень API 2.0, threadsafety=2 и paramstyle="pyformat". Модуль также предоставляет конструкторы типов PEP 249 Date, Time, Timestamp и Binary, а также функции DateFromTicks, TimeFromTicks и TimestampFromTicks. Модуль экспортирует иерархию исключений PEP 249: Warning, Error, InterfaceError, DatabaseError, DataError, OperationalError, IntegrityError, InternalError, ProgrammingError и NotSupportedError. Это те же объекты классов, что и в clickhouse_connect.driver.exceptions, поэтому ошибки драйвера можно перехватывать, импортируя их из любого из этих модулей. Специфичное для драйвера исключение StreamFailureError по-прежнему доступно в clickhouse_connect.driver.exceptions и является подклассом OperationalError.

from clickhouse_connect import dbapi

connection = dbapi.connect(
    host="localhost",
    username="default",
    password="password",
    database="default",
)
cursor = connection.cursor()

try:
    cursor.execute(
        "SELECT name FROM system.tables "
        "WHERE database = %(database)s ORDER BY name LIMIT 5",
        {"database": "system"},
    )
    print(cursor.description)
    print(cursor.fetchall())
finally:
    cursor.close()
    connection.close()

Cursor.execute и Cursor.executemany принимают дополнительные именованные аргументы settings и query_formats. settings передаёт настройки ClickHouse. query_formats применяет форматы чтения по типам ClickHouse, когда оператор возвращает строки, используя то же сопоставление, что и Client.query. Оба метода также принимают доступный только по имени аргумент pyformat_encoded. Его значение по умолчанию True соответствует контракту DB-API pyformat. Диалект SQLAlchemy устанавливает его в False, когда компилятор оператора генерирует необработанные знаки процента, поэтому приложениям обычно не следует задавать его. Параметризованные операции Cursor.executemany выполняются по одному разу для каждого набора параметров, сохраняя семантику привязки SQL и вычисления выражений. При работе через HTTP для каждого набора параметров отправляется отдельный запрос. Если один из последующих наборов параметров завершается с ошибкой, уже выполненные записи остаются закоммиченными. Для таких вставок через executemany значение Cursor.rowcount равно сумме значений written_rows, возвращённых ClickHouse, или -1, если это значение недоступно. Для операторов INSERT, отправленных через Cursor.execute, возвращается 0. Форма совместимости INSERT INTO table (columns) VALUES без плейсхолдеров использует нативную вставку. Оператор INSERT без плейсхолдеров, заканчивающийся на VALUES, вызывает ProgrammingError, если его не удаётся распознать как эту форму совместимости. Приложениям, которым требуется явная массовая вставка в формате Native, следует использовать Client.insert. fetchone, fetchmany и fetchall считывают текущий материализованный результат. Cursor.description определяет null_ok по типу каждого столбца результата. Типы, не допускающие NULL, возвращают False, а допускающие NULL — True, включая обёртки Nullable, Variant и Dynamic. None означает, что допустимость NULL неизвестна. Если запрос, начинающийся с SELECT или WITH без учёта начальных комментариев, не возвращает строк и метаданных столбцов, курсор выполняет запрос метаданных с LIMIT 0, чтобы заполнить description. Если этот запрос метаданных завершается с ошибкой, description остаётся пустым. ClickHouse не поддерживает традиционные транзакции через этот HTTP-интерфейс. Connection.commit() и Connection.rollback() не выполняют никаких действий. Правила параллелизма для идентификатора сеанса по-прежнему действуют, если соединение используется совместно.

Вспомогательные классы и функции

Следующие модули предоставляют дополнительные общедоступные вспомогательные средства, используемые клиентскими приложениями. Версия установленного пакета доступна как строка clickhouse_connect.__version__.

Исключения

Пользовательские исключения, включая иерархию исключений DB-API 2.0, повторно экспортируемую модулем clickhouse_connect.dbapi, определены в clickhouse_connect.driver.exceptions. DatabaseError и OperationalError предоставляют числовой атрибут code с кодом ошибки ClickHouse и атрибут name с символьным именем, например UNKNOWN_TABLE, поэтому приложения могут строить логику на основе exc.code, а не разбирать сообщение. code задается, даже если show_clickhouse_errors отключен, тогда как для name требуется отображение подробностей ошибки (True или "scrub"). Оба имеют значение None, когда недоступны, например при ошибках передачи данных. Используйте show_clickhouse_errors="scrub", когда конечные пользователи должны видеть ошибки SQL без информации о хосте или версии сервера. Этот параметр также управляет сообщениями StreamFailureError в процессе потоковой передачи и общими сообщениями об ошибках передачи данных. Он влияет только на str(exc). Ошибки передачи данных по-прежнему прикрепляются как __cause__, а трассировки стека могут содержать исходные сведения о хосте, URL или текст ошибки библиотеки.

Утилиты ClickHouse SQL

Функции и класс DT64Param в модуле clickhouse_connect.driver.binding можно использовать для корректного формирования и экранирования запросов ClickHouse SQL. Аналогично, функции из модуля clickhouse_connect.driver.parser можно использовать для разбора названий типов данных ClickHouse.

Многопоточные, многопроцессные и асинхронные/событийно-ориентированные сценарии использования

Подробнее об использовании ClickHouse Connect в многопоточных, многопроцессных и асинхронных/событийно-ориентированных приложениях см. в разделе Расширенное использование (многопоточные, многопроцессные и асинхронные/событийно-ориентированные сценарии использования).

AsyncClient

Сведения о непосредственном использовании AsyncClient с asyncio см. в разделе Расширенное использование (AsyncClient).

Управление идентификаторами сеансов ClickHouse

Сведения об управлении идентификаторами сеансов ClickHouse в многопоточных или параллельно работающих приложениях см. в разделе Расширенное использование (Управление идентификаторами сеансов ClickHouse).

Настройка пула HTTP-соединений

Сведения о настройке пула HTTP-соединений для крупных многопоточных приложений см. в разделе Расширенное использование (настройка пула HTTP-соединений).

Последнее изменение 26 сентября 2026 г.

​Инициализация клиента

​Аргументы подключения

​Аргументы HTTPS/TLS

​Аргумент settings

​Примеры создания клиента

​Встроенное backend-соединение chDB

​Жизненный цикл клиента и рекомендации

​Основные принципы

​Основные рекомендации

​Многопоточные приложения

​Правильная очистка

​Когда использовать несколько клиентов

​Общие аргументы методов

​Аргумент parameters

​Привязка на стороне сервера

​Привязка на стороне клиента

​аргумент settings

​Метод command клиента

​Примеры команд

​DDL-операторы

​Простые запросы, возвращающие одиночные значения

​Команды с параметрами

​Команды с настройками

​Метод query клиента Client

​Примеры запросов

​Простой запрос

​Доступ к результатам запроса

​Запрос с параметрами на стороне клиента

​Запрос с параметрами на стороне сервера

​Запрос с настройками

​Объект QueryResult

​Получение результатов запросов с помощью NumPy, Pandas или Arrow

​Методы потокового выполнения запросов в клиенте

​Метод клиента insert

​Примеры

​Базовая построчная вставка

​Вставка в столбцовом формате

​Вставка с явным указанием типов столбцов

​Вставка в определённую базу данных

​Вставка из файлов

​Raw API

​Python DB-API 2.0

​Вспомогательные классы и функции

​Исключения

​Утилиты ClickHouse SQL

​Многопоточные, многопроцессные и асинхронные/событийно-ориентированные сценарии использования

​AsyncClient

​Управление идентификаторами сеансов ClickHouse

​Настройка пула HTTP-соединений

Инициализация клиента

Аргументы подключения

Аргументы HTTPS/TLS

Аргумент settings

Примеры создания клиента

Встроенное backend-соединение chDB

Жизненный цикл клиента и рекомендации

Основные принципы

Основные рекомендации

Многопоточные приложения

Правильная очистка

Когда использовать несколько клиентов

Общие аргументы методов

Аргумент `parameters`

Привязка на стороне сервера

Привязка на стороне клиента

аргумент settings

Метод `command` клиента

Примеры команд

DDL-операторы

Простые запросы, возвращающие одиночные значения

Команды с параметрами

Команды с настройками

Метод `query` клиента `Client`

Примеры запросов

Простой запрос

Доступ к результатам запроса

Запрос с параметрами на стороне клиента

Запрос с параметрами на стороне сервера

Запрос с настройками

Объект `QueryResult`

Получение результатов запросов с помощью NumPy, Pandas или Arrow

Методы потокового выполнения запросов в клиенте

Метод клиента `insert`

Примеры

Базовая построчная вставка

Вставка в столбцовом формате

Вставка с явным указанием типов столбцов

Вставка в определённую базу данных

Вставка из файлов

Raw API

Python DB-API 2.0

Вспомогательные классы и функции

Исключения

Утилиты ClickHouse SQL

Многопоточные, многопроцессные и асинхронные/событийно-ориентированные сценарии использования

AsyncClient

Управление идентификаторами сеансов ClickHouse

Настройка пула HTTP-соединений