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

ClickHouse Connect предоставляет ряд дополнительных опций для более сложных сценариев использования.

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

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

from clickhouse_connect import common

common.set_setting('autogenerate_session_id', False)
common.get_setting('invalid_setting_action')
'drop'

Примечание

Эти общие настройки autogenerate_session_id, product_name и readonly всегда следует изменять до создания клиента с помощью метода clickhouse_connect.get_client. Изменение этих настроек после создания клиента не влияет на поведение уже существующих клиентов.

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

Setting Name	Default	Options	Description
autogenerate_session_id	True	True, False	Автоматически генерировать новый идентификатор сеанса UUID(1) (если не указан) для каждого клиентского сеанса. Если идентификатор сеанса не указан (ни на уровне клиента, ни на уровне запроса), ClickHouse сгенерирует случайный внутренний идентификатор для каждого запроса.
dict_parameter_format	'json'	'json', 'map'	Определяет, должны ли параметризованные запросы преобразовывать словарь Python в JSON или в синтаксис ClickHouse Map. json следует использовать для вставки в столбцы JSON, map — для столбцов ClickHouse типа Map.
invalid_setting_action	'error'	'drop', 'send', 'error'	Действие при передаче некорректной или доступной только для чтения настройки (как для клиентского сеанса, так и для запроса). Если drop, настройка будет проигнорирована; если send, настройка будет отправлена в ClickHouse; если error, на стороне клиента будет сгенерировано исключение ProgrammingError.
max_connection_age	600		Максимальное число секунд, в течение которых соединение HTTP Keep Alive будет оставаться открытым и переиспользоваться. Это предотвращает концентрацию соединений на одном узле ClickHouse за балансировщиком нагрузки/прокси. По умолчанию 10 минут.
product_name			Строка, которая передаётся вместе с запросом в ClickHouse для отслеживания приложения, использующего ClickHouse Connect. Должна иметь формат <product name;&gl/<product version>.
readonly	0	0, 1	Неявные настройки ClickHouse "read_only" для версий до 19.17. Может быть установлена в значение, соответствующее ClickHouse "read_only" для настроек, чтобы обеспечить работу с очень старыми версиями ClickHouse.
send_os_user	True	True, False	Включать обнаруженного пользователя операционной системы в клиентскую информацию, отправляемую в ClickHouse (строка HTTP User-Agent).
send_integration_tags	True	True, False	Включать используемые интеграционные библиотеки и их версии (например, Pandas/SQLAlchemy/и т. д.) в клиентскую информацию, отправляемую в ClickHouse (строка HTTP User-Agent).
use_protocol_version	True	True, False	Использовать версию клиентского протокола. Это необходимо для столбцов DateTime с часовыми поясами, но не работает с текущей версией chproxy.
max_error_size	1024		Максимальное количество символов, которые будет возвращено в сообщениях об ошибке клиента. Установите для этой настройки значение 0, чтобы получать полное сообщение об ошибке ClickHouse. По умолчанию 1024 символа.
http_buffer_size	10MB		Размер (в байтах) "внутрипамятного" буфера, используемого для потоковых HTTP-запросов.
preserve_pandas_datetime_resolution	False	True, False	Если True и используется pandas 2.x, сохраняет разрешение типов datetime64/timedelta64 (например, 's', 'ms', 'us', 'ns'). Если False (или при pandas <2.x), приводит к наносекундному разрешению ('ns') для совместимости.

Сжатие

ClickHouse Connect поддерживает сжатие lz4, zstd, brotli и gzip как для результатов запросов, так и для вставок. Всегда учитывайте, что использование сжатия обычно связано с компромиссом между сетевой пропускной способностью/скоростью передачи и нагрузкой на CPU (как на клиенте, так и на сервере).

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

Сжатие управляется параметром compress при вызове фабричного метода clickhouse_connect.get_client. По умолчанию compress установлен в True, что включает настройки сжатия по умолчанию. Для запросов, выполняемых методами клиента query, query_np и query_df, ClickHouse Connect добавит заголовок Accept-Encoding с кодировками lz4, zstd, br (brotli, если библиотека brotli установлена), gzip и deflate к запросам, выполняемым методом клиента query (и, косвенно, query_np и query_df). (Для большинства запросов сервер ClickHouse вернёт полезную нагрузку, сжатую с помощью zstd.) Для вставок по умолчанию ClickHouse Connect будет сжимать блоки вставки с помощью lz4 и отправлять HTTP‑заголовок Content-Encoding: lz4.

Параметр compress метода get_client также может быть установлен в конкретный метод сжатия — один из lz4, zstd, br или gzip. Этот метод затем будет использоваться как для вставок, так и для результатов запросов (если он поддерживается сервером ClickHouse). Необходимые библиотеки сжатия zstd и lz4 теперь устанавливаются по умолчанию вместе с ClickHouse Connect. Если указано br/brotli, библиотека brotli должна быть установлена отдельно.

Обратите внимание, что клиентские методы raw* не используют сжатие, указанное в конфигурации клиента.

Мы также не рекомендуем использовать сжатие gzip, поскольку оно значительно медленнее альтернатив как при сжатии, так и при распаковке данных.

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

ClickHouse Connect добавляет базовую поддержку HTTP-прокси с использованием библиотеки urllib3. Он распознаёт стандартные переменные окружения HTTP_PROXY и HTTPS_PROXY. Имейте в виду, что использование этих переменных окружения повлияет на всех клиентов, создаваемых методом clickhouse_connect.get_client. Либо, чтобы настраивать прокси отдельно для каждого клиента, вы можете использовать аргументы http_proxy или https_proxy метода get_client. Подробную информацию о реализации поддержки HTTP-прокси см. в документации urllib3.

Чтобы использовать SOCKS-прокси, вы можете передать urllib3 SOCKSProxyManager в качестве аргумента pool_mgr в get_client. Обратите внимание, что для этого потребуется установить библиотеку PySocks либо напрямую, либо с использованием опции [socks] для зависимости urllib3.

Тип данных JSON «старого» образца

Экспериментальный тип данных Object (или Object('json')) признан устаревшим и не должен использоваться в продакшн-среде. ClickHouse Connect по-прежнему обеспечивает ограниченную поддержку этого типа данных для сохранения обратной совместимости. Обратите внимание, что эта поддержка не распространяется на запросы, от которых ожидается возврат «верхнеуровневых» или «родительских» значений JSON в виде словарей или эквивалентных структур; такие запросы приведут к возникновению исключения.

«Новые» типы данных Variant/Dynamic/JSON (экспериментальная возможность)

Начиная с релиза 0.8.0, clickhouse-connect предоставляет экспериментальную поддержку новых (также экспериментальных) типов данных ClickHouse: Variant, Dynamic и JSON.

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

• JSON-данные можно вставлять как словарь Python или как JSON-строку, содержащую JSON-объект {}. Другие формы JSON-данных не поддерживаются.
• Запросы, использующие подколонки/пути для этих типов, будут возвращать тип подколонки.
• Дополнительные примечания по использованию см. в основной документации ClickHouse.

Известные ограничения

• Каждый из этих типов должен быть включён в настройках ClickHouse перед использованием.
• «Новый» тип JSON доступен начиная с релиза ClickHouse 24.8.
• Из-за внутренних изменений формата clickhouse-connect совместим с типами Variant только начиная с релиза ClickHouse 24.7.
• Возвращаемые JSON-объекты будут содержать не более max_dynamic_paths элементов (по умолчанию 1024). Это будет исправлено в одном из будущих релизов.
• Вставки в столбцы Dynamic всегда будут представлять собой строковое представление значения Python. Это будет исправлено в одном из будущих релизов после того, как будет решена задача https://github.com/ClickHouse/ClickHouse/issues/70395.
• Реализация новых типов не была оптимизирована в C-коде, поэтому производительность может быть несколько ниже, чем у более простых, уже устоявшихся типов данных.