Дополнительные параметры

ClickHouse Connect предлагает ряд дополнительных параметров для расширенных сценариев использования.

Глобальные настройки

Несколько настроек глобально определяют поведение ClickHouse Connect. Доступ к ним осуществляется из пакета верхнего уровня common:

from clickhouse_connect import common

common.set_setting("autogenerate_session_id", False)
print(common.get_setting("invalid_setting_action"))
# Output: error

Note

Настройте параметры создания клиентов до их создания. Такие параметры, как генерируемые ID сеанса и запроса, а также идентификатор продукта, копируются в состояние конкретного клиента, поэтому последующие глобальные изменения не применяются к существующим клиентам. Параметры привязки и вставки работают иначе. Значения naive_datetime_binding и dict_parameter_format считываются при привязке параметров. Значение naive_datetime_insert считывается при сериализации нативного столбца для вставки, содержащего объекты Python datetime или строки ISO DateTime64. Изменения этих параметров влияют на существующих клиентов. Контекст вставки, пригодный для повторного использования, использует текущее значение naive_datetime_insert для каждой вставки.

В настоящее время определены следующие глобальные параметры:

Имя параметра	По умолчанию	Варианты	Описание
`autogenerate_session_id`	`True`	`True`, `False`	Генерирует UUID ID сеанса для каждого синхронного клиента, если ID сеанса не указан. Асинхронная фабрика по умолчанию переопределяет это значение на `False`.
`autogenerate_query_id`	`True`	`True`, `False`	Генерирует UUID ID запроса для каждого запроса, если он не указан.
`dict_parameter_format`	`"json"`	`"json"`, `"map"`	Форматирует словари Python, используемые при привязке параметров, как литералы JSON или Map ClickHouse.
`invalid_setting_action`	`"error"`	`"drop"`, `"send"`, `"error"`	Действие для параметра, который сервер помечает как только для чтения. `drop` игнорирует его, `send` передаёт его серверу, `error` вызывает `ProgrammingError`. Параметры, отсутствующие в `system.settings` для текущего пользователя, например параметр, заданный для роли как `CHANGEABLE_IN_READONLY`, передаются серверу, чтобы тот мог принять или отклонить их, если не выбрано действие `drop`.
`naive_datetime_binding`	`"wall"`	`"wall"`, `"legacy"`	Управляет привязкой наивных параметров запроса `datetime`. `wall` форматирует наивные значения даты и времени без изменений. `legacy` восстанавливает прежнее поведение преобразования с использованием локального времени хоста. Добавьте `tzinfo`, чтобы сохранить момент времени.
`naive_datetime_insert`	`"local"`	`"local"`, `"server"`	Управляет вставкой объектов Python с наивными значениями `datetime` и наивных строк ISO, принимаемых `DateTime64`. `local` использует часовой пояс процесса для совместимости. `server` использует объявленный часовой пояс столбца, а затем часовой пояс сервера. Столбцы NumPy и Pandas с dtype `datetime64` не изменяются.
`max_connection_age`	`600`	Любое количество секунд	Максимальный срок использования повторно используемого HTTP-соединения keep-alive. Ротация помогает распределять соединения между узлами за балансировщиком нагрузки.
`product_name`	`""`	Любая строка	Идентификатор продукта, добавляемый в информацию о клиенте. Используйте, например, значение `"my-product/1.0"`.
`readonly`	`0`	`0`, `1`	Устаревший параметр без действия, сохранённый для совместимости с 1.x. Клиент напрямую считывает параметр сервера `readonly`.
`send_os_user`	`True`	`True`, `False`	Включает обнаруженного пользователя операционной системы в информацию о клиенте.
`send_integration_tags`	`True`	`True`, `False`	Включает в HTTP User-Agent интеграции, используемые клиентом, например Pandas или SQLAlchemy.
`use_protocol_version`	`True`	`True`, `False`	Согласовывает версию протокола клиента, используемую функциями формата Native, например метаданными часового пояса столбца `DateTime`. Отключите этот параметр для прокси, которые отклоняют `client_protocol_version`.
`max_error_size`	`1024`	Любое неотрицательное целое число	Максимальное число символов, включаемых в сообщение об ошибке клиента. Используйте `0` для полного сообщения.
`http_buffer_size`	`10485760`	Байты	Размер буфера в памяти для потоковых HTTP-запросов; по умолчанию 10 МиБ.

Сжатие

ClickHouse Connect поддерживает сжатие ответов lz4, zstd, brotli, gzip и deflate. Нативные вставки поддерживают lz4, zstd, brotli и gzip. Сжатие уменьшает объём передаваемых по сети данных ценой дополнительного времени CPU.

Чтобы получать сжатые данные, на сервере ClickHouse параметр enable_http_compression должен быть установлен в 1, либо у пользователя должно быть разрешение изменять этот параметр для отдельных запросов.

Сжатием управляет аргумент compress у get_client и get_async_client. Значение по умолчанию, True, объявляет все доступные кодировки ответов и сжимает блоки нативной вставки с помощью lz4. Установите compress=False, чтобы отключить сжатие, или передайте одно из значений "lz4", "zstd", "br" или "gzip", чтобы запросить конкретный метод.

Низкоуровневые методы client не используют клиентскую настройку compress. raw_query и raw_stream возвращают несжатые данные, а raw_insert принимает собственный аргумент compression, описывающий сжатие, уже применённое к полезной нагрузке.

Поддержка lz4 и zstd устанавливается вместе с ClickHouse Connect. В Python 3.14 zstd использует модуль стандартной библиотеки compression.zstd. В Python 3.10–3.13 используется backports.zstd. Пользовательский интерпретатор CPython 3.14+, собранный без поддержки zstd, всё равно импортируется; zstd исключается из списка доступных методов, а ошибка возникает только при явном запросе zstd. Поддержка Brotli не является обязательной и должна быть установлена отдельно перед использованием compress="br".

Для рабочих нагрузок ClickHouse gzip обычно медленнее, чем lz4 или zstd.

Поддержка HTTP-прокси

ClickHouse Connect распознаёт стандартные переменные окружения HTTP_PROXY и HTTPS_PROXY. Эти переменные применяются ко всем клиентам в рамках процесса. Чтобы настроить прокси отдельно для каждого клиента, передайте http_proxy или https_proxy в get_client или get_async_client.

Синхронный клиент использует urllib3. Чтобы использовать SOCKS-прокси, установите PySocks и передайте urllib3.contrib.socks.SOCKSProxyManager в качестве аргумента pool_mgr в get_client. Аргумент pool_mgr не поддерживается асинхронным клиентом.

Типы данных Variant, Dynamic и JSON

ClickHouse Connect поддерживает актуальные типы данных ClickHouse: Variant, Dynamic и JSON. Устаревший тип Object('json') был удалён в clickhouse-connect 0.14 и не поддерживается.

Примечания по использованию

Значения Variant считываются как соответствующий тип Python. При нативной вставке элемент выбирается по типу значения Python.
Если нескольким элементам Variant соответствует один и тот же тип Python, оберните значение с помощью clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName"), чтобы явно выбрать нужный элемент.
Формат чтения typed для Variant возвращает объекты TypedVariant(value, type_name) и сохраняет исходный тип элемента. Чтобы включить его, используйте query_formats={"Variant": "typed"}.
Значения Dynamic считываются как соответствующий тип Python. В настоящее время вставки отправляются в строковом представлении.
Значения JSON можно вставлять как словари Python или JSON-строки, содержащие объекты. Формат чтения по умолчанию возвращает словари; чтобы возвращать JSON-строки, используйте формат чтения "string".
Запросы, выбирающие подстолбец Variant, Dynamic или JSON, возвращают конкретный тип этого подстолбца.

Некоторые значения, хранящиеся в области shared-data столбцов JSON или Dynamic, используют типы, которые клиент пока не может декодировать. Такие значения возвращаются как raw bytes. Для этих сложных типов также используется путь преобразования на pure Python, поэтому они могут работать медленнее, чем обычные скалярные типы.