Глобальные настройки
common:
Эти общие настройки
autogenerate_session_id, product_name и readonly всегда следует изменять до создания клиента с помощью метода clickhouse_connect.get_client. Изменение этих настроек после создания клиента не влияет на поведение уже существующих клиентов.| Имя настройки | По умолчанию | Варианты | Описание |
|---|---|---|---|
| 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 за балансировщиком нагрузки/proxy. По умолчанию — 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/etc.) в информацию о клиенте, отправляемую в 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, сохраняет разрешение dtype datetime64/timedelta64 (например, ‘s’, ‘ms’, ‘us’, ‘ns’). Если False (или при pandas <2.x), для совместимости приводит к наносекундному разрешению (‘ns’). |
Сжатие
lz4, zstd, brotli и gzip как для результатов запросов, так и для вставок. Помните, что использование сжатия обычно связано с компромиссом между пропускной способностью сети/скоростью передачи и нагрузкой на CPU (как на клиенте, так и на сервере).
Чтобы получать сжатые данные, на сервере ClickHouse параметр enable_http_compression должен быть установлен в значение 1, либо у пользователя должно быть разрешение изменять этот параметр для каждого запроса отдельно.
Сжатием управляет параметр compress при вызове фабричного метода clickhouse_connect.get_client. По умолчанию compress имеет значение True, что включает настройки сжатия по умолчанию. Для запросов, выполняемых методами клиента query, query_np и query_df, ClickHouse Connect добавляет HTTP-заголовок 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-прокси
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-значения верхнего уровня или родительские JSON-значения в виде словарей либо аналогичных структур; такие запросы приводят к исключению.
«Новые» типы данных Variant/Dynamic/JSON (экспериментальная возможность)
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, поэтому производительность может быть несколько ниже, чем у более простых и устоявшихся типов данных.