> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Дополнительные параметры для ClickHouse Connect
# Дополнительные параметры
ClickHouse Connect предлагает ряд дополнительных параметров для расширенных сценариев использования.
## Глобальные настройки
Несколько настроек глобально определяют поведение ClickHouse Connect. Доступ к ним осуществляется из пакета верхнего уровня `common`:
```python theme={null}
from clickhouse_connect import common
common.set_setting("autogenerate_session_id", False)
print(common.get_setting("invalid_setting_action"))
# Output: error
```
Настройте параметры создания клиентов до их создания. Такие параметры, как генерируемые 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, поэтому они могут работать медленнее, чем обычные скалярные типы.