Глобальные настройки
common:
Эти общие настройки
autogenerate_session_id, product_name и readonly всегда следует изменять до создания клиента с помощью метода clickhouse_connect.get_client. Изменение этих настроек после создания клиента не влияет на поведение уже существующих клиентов.Сжатие
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, поэтому производительность может быть несколько ниже, чем у более простых и устоявшихся типов данных.