Интеграция Python с ClickHouse Connect

Используйте экземпляр клиента ClickHouse Connect для подключения к службе ClickHouse Cloud:

подсказка

Используйте собранные ранее данные для подключения. Службы ClickHouse Cloud требуют TLS, поэтому используйте порт 8443.

Взаимодействуйте с вашей базой данных

Чтобы выполнить команду SQL ClickHouse, используйте метод клиента command:

Чтобы вставить пакет данных, используйте метод клиента insert с двумерным массивом строк и значений:

Чтобы извлечь данные с использованием SQL ClickHouse, используйте метод клиента query:

API драйвера ClickHouse Connect

Примечание: Рекомендуется передавать именованные аргументы для большинства методов API с учетом количества возможных аргументов, большинство из которых являются необязательными.

Методы, не документированные здесь, не считаются частью API и могут быть удалены или изменены.

Инициализация клиента

Класс clickhouse_connect.driver.client предоставляет основной интерфейс между приложением на Python и сервером базы данных ClickHouse. Используйте функцию clickhouse_connect.get_client, чтобы получить экземпляр Client, который принимает следующие аргументы:

Аргументы подключения

Параметр	Тип	Значение по умолчанию	Описание
interface	str	http	Должен быть http или https.
host	str	localhost	Имя хоста или IP-адрес сервера ClickHouse. Если не установлено, будет использовано localhost.
port	int	8123 или 8443	Порт ClickHouse для HTTP или HTTPS. Если не установлен, по умолчанию используется 8123 или 8443, если secure=True или interface=https.
username	str	default	Имя пользователя ClickHouse. Если не установлено, будет использован пользователь ClickHouse по умолчанию default.
password	str	<пустая строка>	Пароль для username.
database	str	None	База данных по умолчанию для подключения. Если не установлено, ClickHouse Connect будет использовать базу данных по умолчанию для username.
secure	bool	False	Использовать https/TLS. Это переопределяет выводимые значения из аргументов интерфейса или порта.
dsn	str	None	Строка в стандартном формате DSN (Data Source Name). Другие значения подключения (такие как хост или пользователь) будут извлечены из этой строки, если не установлены иным образом.
compress	bool или str	True	Включить сжатие для вставок HTTP ClickHouse и результатов запросов. См. Дополнительные параметры (Сжатие)
query_limit	int	0 (без ограничений)	Максимальное количество строк для возврата для любого ответа query. Установите это значение равным нулю, чтобы вернуть неограниченное количество строк. Обратите внимание, что большие ограничения запроса могут вызвать исключения нехватки памяти, если результаты не передаются потоком, так как все результаты загружаются в память сразу.
query_retries	int	2	Максимальное количество повторных попыток для запроса query. Повторные попытки будут осуществляться только для "повторяемых" HTTP-ответов. Запросы command или insert не будут автоматически повторяться драйвером, чтобы избежать непреднамеренных дубликатов запросов.
connect_timeout	int	10	Тайм-аут HTTP подключения в секундах.
send_receive_timeout	int	300	Тайм-аут отправки/получения для HTTP-соединения в секундах.
client_name	str	None	client_name, добавляемый к заголовку HTTP User Agent. Установите это, чтобы отслеживать клиентские запросы в системном журнале ClickHouse.
pool_mgr	obj	<менеджер пула по умолчанию>	Менеджер пула библиотеки urllib3, который будет использоваться. Для продвинутых случаев использования, требующих нескольких пулов соединений для разных хостов.
http_proxy	str	None	Адрес HTTP прокси (эквивалентно установке переменной окружения HTTP_PROXY).
https_proxy	str	None	Адрес HTTPS прокси (эквивалентно установке переменной окружения HTTPS_PROXY).
apply_server_timezone	bool	True	Использовать часовой пояс сервера для результатов запросов с учетом часового пояса. См. Приоритет часовых поясов

Аргументы HTTPS/TLS

Параметр	Тип	Значение по умолчанию	Описание
verify	bool	True	Подтвердить сертификат TLS/SSL сервера ClickHouse (имя хоста, истечение и т. д.), если используется HTTPS/TLS.
ca_cert	str	None	Если verify=True, путь к файлу корневого Сертификата Удостоверяющего Центра для подтверждения сертификата сервера ClickHouse в формате .pem. Игнорируется, если verify равно False. Это не обязательно, если сертификат сервера ClickHouse является глобально доверенным корнем, как это проверяется операционной системой.
client_cert	str	None	Путь к файлу клиентского сертификата TLS в формате .pem (для взаимной аутентификации TLS). Файл должен содержать полную цепочку сертификатов, включая любые промежуточные сертификаты.
client_cert_key	str	None	Путь к закрытому ключу для клиентского сертификата. Требуется, если закрытый ключ не включен в файл ключа клиентского сертификата.
server_host_name	str	None	Имя хоста сервера ClickHouse, определяемое CN или SNI его сертификата TLS. Установите это, чтобы избежать ошибок SSL при подключении через прокси или туннель с другим именем хоста
tls_mode	str	None	Управляет расширенным поведением TLS. proxy и strict не инициируют взаимное TLS-соединение ClickHouse, но отправляют клиентский сертификат и ключ. mutual предполагает взаимную аутентификацию по сертификату клиента. Поведение по умолчанию/None является mutual

Аргумент настроек

Наконец, аргумент settings для get_client используется для передачи дополнительных настроек ClickHouse серверу для каждого клиентского запроса. Обратите внимание, что в большинстве случаев пользователи с доступом readonly=1 не могут изменять настройки, отправленные с запросом, поэтому ClickHouse Connect удалит такие настройки в последнем запросе и зарегистрирует предупреждение. Следующие настройки применяются только к HTTP-запросам/сессиям, используемым ClickHouse Connect, и не документируются как общие настройки ClickHouse.

Настройка	Описание
buffer_size	Размер буфера (в байтах), используемый сервером ClickHouse перед записью в HTTP-канал.
session_id	Уникальный идентификатор сессии для ассоциации связанных запросов на сервере. Необходим для временных таблиц.
compress	Указывает, должен ли сервер ClickHouse сжимать данные POST-ответа. Эта настройка должна использоваться только для "сырых" запросов.
decompress	Указывает, должны ли данные, отправляемые на сервер ClickHouse, быть распакованы. Эта настройка должна использоваться только для "сырых" вставок.
quota_key	Ключ квоты, связанный с этим запросом. См. документацию сервера ClickHouse по квотам.
session_check	Используется для проверки статуса сессии.
session_timeout	Количество секунд бездействия, после которых идентификатором сессии будет превышено время ожидания, и он больше не будет считаться действительным. Значение по умолчанию — 60 секунд.
wait_end_of_query	Буферизует весь ответ на сервере ClickHouse. Эта настройка требуется для возврата сводной информации и автоматически устанавливается для нестриминговых запросов.

Для других настроек ClickHouse, которые могут быть отправлены с каждым запросом, см. документацию ClickHouse.

Примеры создания клиента

• Без каких-либо параметров клиент ClickHouse Connect подключится к порту HTTP по умолчанию на localhost с пользователем по умолчанию и без пароля:

• Подключение к безопасному (https) внешнему серверу ClickHouse:

• Подключение с идентификатором сессии и другими пользовательскими параметрами подключения и настройками ClickHouse.

Общие аргументы методов

Несколько методов клиента используют один или оба общих аргумента parameters и settings. Эти именованные аргументы описаны ниже.

Аргумент параметров

Методы ClickHouse Connect Client query* и command принимают необязательный именованный аргумент parameters, используемый для связывания выражений Python с выражением значения ClickHouse. Доступны два типа связывания.

Связывание на стороне сервера

ClickHouse поддерживает связывание на стороне сервера для большинства значений запросов, где связанное значение отправляется отдельно от запроса как HTTP-параметр запроса. ClickHouse Connect добавит соответствующие параметры запроса, если обнаружит выражение связывания в форме {<name>:<datatype>}. Для связывания на стороне сервера аргумент parameters должен быть словарем Python.

• Связывание на стороне сервера с помощью словаря Python, значение DateTime и строковое значение:

ВАЖНО — Связывание на стороне сервера поддерживается (сервером ClickHouse) только для запросов SELECT. Оно не работает для ALTER, DELETE, INSERT или других типов запросов. Это может измениться в будущем, см. https://github.com/ClickHouse/ClickHouse/issues/42092.

Связывание на стороне клиента

ClickHouse Connect также поддерживает связывание параметров на стороне клиента, что может обеспечить более гибкость в создании параметрических SQL-запросов. Для связывания на стороне клиента аргумент parameters должен быть словарем или последовательностью. Связывание на стороне клиента использует форматирование строк Python в стиле "printf" для замены параметров.

Обратите внимание, что в отличие от связывания на стороне сервера, связывание на стороне клиента не работает для идентификаторов баз данных, таких как имя базы данных, таблицы или столбца, поскольку форматирование строк Python не может различить разные типы строк, и они должны форматироваться по-разному (обратные кавычки или двойные кавычки для идентификаторов баз данных, одинарные кавычки для значений данных).

• Пример со словарем Python, значением DateTime и экранированием строк:

• Пример с последовательностью Python (кортеж), Float64 и IPv4Address:

примечание

Чтобы связать аргументы DateTime64 (типы ClickHouse с субсекундной точностью), требуется один из двух пользовательских подходов:

• Оберните значение datetime.datetime Python в новый класс DT64Param, например,
  • Если использовать словарь значений параметров, добавьте строку _64 к имени параметра

Аргумент настроек

Все ключевые методы "insert" и "select" клиента ClickHouse Connect принимают необязательный именованный аргумент settings для передачи параметров настроек пользователя ClickHouse для включенного SQL-запроса. Аргумент settings должен быть словарем. Каждый элемент должен быть именем настройки ClickHouse и его соответствующим значением. Обратите внимание, что значения будут преобразовываться в строки при отправке на сервер в качестве параметров запроса.

Как и в случае с настройками на уровне клиента, ClickHouse Connect удалит любые настройки, которые сервер помечает как readonly=1, с соответствующим сообщением в журнале. Настройки, которые применяются только к запросам через HTTP-интерфейс ClickHouse, всегда действительны. Эти настройки описаны в API метода get_client.

Пример использования настроек ClickHouse:

Метод command клиента {#client-command-method}

Используйте метод Client.command для отправки SQL-запросов на сервер ClickHouse, которые обычно не возвращают данные или возвращают единственное примитивное или массивное значение, а не полный набор данных. Этот метод принимает следующие параметры:

Параметр	Тип	Значение по умолчанию	Описание
cmd	str	Обязательный	SQL-оператор ClickHouse, который возвращает единственное значение или единственную строку значений.
parameters	dict or iterable	None	См. описание параметров.
data	str or bytes	None	Необязательные данные для включения с командой в теле POST-запроса.
settings	dict	None	См. описание настроек.
use_database	bool	True	Использовать базу данных клиента (указанную при создании клиента). Ложь означает, что команда будет использовать базу данных по умолчанию сервера ClickHouse для подключенного пользователя.
external_data	ExternalData	None	Объект ExternalData, содержащий файл или двоичные данные для использования с запросом. См. Расширенные запросы (внешние данные)

• command можно использовать для DDL-операций. Если SQL "команда" не возвращает данные, возвращается вместо этого словарь "резюме запроса". Этот словарь инкапсулирует заголовки ClickHouse X-ClickHouse-Summary и X-ClickHouse-Query-Id, включая пары ключ/значение written_rows,written_bytes и query_id.

• command также можно использовать для простых запросов, которые возвращают только одну строку:

Клиентский метод query {#client-query-method}

Метод Client.query является основным способом получения одного "пакета" данных из ClickHouse Server. Он использует нативный формат ClickHouse через HTTP для эффективной передачи больших наборов данных (до примерно миллиона строк). Этот метод принимает следующие параметры.

Параметр	Тип	По умолчанию	Описание
query	str	Обязательный	SQL-запрос SELECT или DESCRIBE для ClickHouse.
parameters	dict или iterable	Нет	См. описание параметров.
settings	dict	Нет	См. описание настроек.
query_formats	dict	Нет	Спецификация форматирования типов данных для результирующих значений. См. Расширенное использование (Чтение форматов)
column_formats	dict	Нет	Форматирование типа данных по колонкам. См. Расширенное использование (Чтение форматов)
encoding	str	Нет	Кодировка, используемая для преобразования колонок типа String в строки Python. По умолчанию используется UTF-8, если не указано иное.
use_none	bool	True	Использовать тип Python None для NULL-значений ClickHouse. Если False, используйте значение по умолчанию для типа данных (например, 0) для NULL-значений ClickHouse. Обратите внимание – по умолчанию для NumPy/Pandas используется False по причинам производительности.
column_oriented	bool	False	Возвращать результаты в виде последовательности колонок, а не строк. Полезно для преобразования данных Python в другие форматы данных, ориентированные на колонки.
query_tz	str	Нет	Название часового пояса из базы данных zoneinfo. Этот часовой пояс будет применяться ко всем объектам datetime или Pandas Timestamp, возвращаемым запросом.
column_tzs	dict	Нет	Словарь, связывающий имена колонок с названиями часовых поясов. Подобно query_tz, но позволяет указывать разные часовые пояса для разных колонок.
use_extended_dtypes	bool	True	Использовать расширенные типы данных Pandas (такие как StringArray), а также pandas.NA и pandas.NaT для значений NULL ClickHouse. Применяется только к методам query_df и query_df_stream.
external_data	ExternalData	Нет	Объект ExternalData, содержащий файл или двоичные данные, которые будут использованы в запросе. См. Расширенные запросы (Внешние данные)
context	QueryContext	Нет	Репрезентативный объект QueryContext, который может быть использован для инкапсуляции аргументов вышеуказанного метода. См. Расширенные запросы (QueryContexts)

Объект QueryResult

Базовый метод query возвращает объект QueryResult с следующими публичными свойствами:

• result_rows -- Матрица данных, возвращаемых в виде последовательности строк, где каждый элемент строки является последовательностью значений колонок.
• result_columns -- Матрица данных, возвращаемых в виде последовательности колонок, где каждый элемент колонки является последовательностью значений строки для данной колонки.
• column_names -- Кортеж строк, представляющий имена колонок в result_set.
• column_types -- Кортеж экземпляров ClickHouseType, представляющий тип данных ClickHouse для каждой колонки в result_columns.
• query_id -- ClickHouse query_id (полезен для анализа запроса в таблице system.query_log).
• summary -- Любые данные, возвращенные заголовком HTTP-ответа X-ClickHouse-Summary.
• first_item -- Удобное свойство для получения первой строки ответа в виде словаря (ключи – имена колонок).
• first_row -- Удобное свойство для возврата первой строки результата.
• column_block_stream -- Генератор результатов запроса в колонкоориентированном формате. Это свойство не должно быть непосредственно использовано (см. ниже).
• row_block_stream -- Генератор результатов запроса в строкоориентированном формате. Это свойство не должно быть непосредственно использовано (см. ниже).
• rows_stream -- Генератор результатов запроса, который возвращает одну строку за вызов. Это свойство не должно быть непосредственно использовано (см. ниже).
• summary -- Как описано в методе command, словарь информации о сводке, возвращенной ClickHouse.

Свойства *_stream возвращают Python Context, который может быть использован как итератор для возвращенных данных. Они должны быть доступны только косвенно с использованием методов Client *_stream.

Полные детали потоковой обработки результатов запроса (с использованием объектов StreamContext) изложены в Расширенные запросы (Потоковые запросы).

Потребление результатов запроса с помощью NumPy, Pandas или Arrow

Существуют три специализированные версии основного метода query:

• query_np -- Эта версия возвращает массив NumPy вместо QueryResult ClickHouse Connect.
• query_df -- Эта версия возвращает DataFrame Pandas вместо QueryResult ClickHouse Connect.
• query_arrow -- Эта версия возвращает таблицу PyArrow. Она использует формат ClickHouse Arrow напрямую, поэтому принимает только три аргумента, общие с основным методом query: query, parameters и settings. В дополнение, есть дополнительный аргумент use_strings, который определяет, будет ли таблица Arrow отображать типы String ClickHouse как строки (если True) или байты (если False).

Клиентские методы потокового запроса

Клиент ClickHouse Connect предоставляет несколько методов для извлечения данных в виде потока (реализованных как генераторы Python):

• query_column_block_stream -- Возвращает данные запроса в блоках в виде последовательности колонок, используя нативный объект Python.
• query_row_block_stream -- Возвращает данные запроса как блок строк, используя нативный объект Python.
• query_rows_stream -- Возвращает данные запроса в виде последовательности строк, используя нативный объект Python.
• query_np_stream -- Возвращает каждый блок данных запроса ClickHouse как массив NumPy.
• query_df_stream -- Возвращает каждый блок данных запроса ClickHouse как DataFrame Pandas.
• query_arrow_stream -- Возвращает данные запроса в блоках записей PyArrow.

Каждый из этих методов возвращает объект ContextStream, который должен быть открыт с помощью оператора with для начала потребления потока. См. Расширенные запросы (Потоковые запросы) для деталей и примеров.

Клиентский метод insert {#client-insert-method}

Для распространенного случая вставки нескольких записей в ClickHouse существует метод Client.insert. Он принимает следующие параметры:

Параметр	Тип	По умолчанию	Описание
table	str	Обязательный	Таблица ClickHouse, в которую осуществляется вставка. Допускается полное имя таблицы (включая базу данных).
data	Последовательность последовательностей	Обязательный	Матрица данных для вставки, либо последовательность строк, каждая из которых является последовательностью значений колонок, либо последовательность колонок, каждая из которых является последовательностью значений строк.
column_names	Последовательность str, или str	'*'	Список имен колонок для матрицы данных. Если используется '*', ClickHouse Connect выполнит "предварительный запрос" для извлечения всех имен колонок для таблицы.
database	str	''	Целевая база данных для вставки. Если не указана, будет использована база данных клиента.
column_types	Последовательность ClickHouseType	Нет	Список экземпляров ClickHouseType. Если не указаны ни column_types, ни column_type_names, ClickHouse Connect выполнит "предварительный запрос" для извлечения всех типов колонок для таблицы.
column_type_names	Последовательность имен типов ClickHouse	Нет	Список имен типов данных ClickHouse. Если не указаны ни column_types, ни column_type_names, ClickHouse Connect выполнит "предварительный запрос" для извлечения всех типов колонок для таблицы.
column_oriented	bool	False	Если True, аргумент data предполагается как последовательность колонок (в противном случае data интерпретируется как последовательность строк).
settings	dict	Нет	См. описание настроек.
insert_context	InsertContext	Нет	Повторно используемый объект InsertContext, который может быть использован для инкапсуляции аргументов вышеуказанного метода. См. Расширенные вставки (InsertContexts).

Этот метод возвращает словарь "резюме запроса", как описано в методе "command". Исключение будет вызвано, если вставка не удалась по какой-либо причине.

Существуют две специализированные версии основного метода insert:

• insert_df -- Вместо последовательности Python последовательностей в аргументе data, второй параметр этого метода требует аргумент df, который должен быть экземпляром DataFrame Pandas. ClickHouse Connect автоматически обрабатывает DataFrame как источник данных ориентированный на колонки, поэтому параметр column_oriented не требуется и недоступен.
• insert_arrow -- Вместо последовательности Python последовательностей в аргументе data, этот метод требует arrow_table. ClickHouse Connect передает таблицу Arrow без изменений на сервер ClickHouse для обработки, так что только аргументы database и settings доступны в дополнение к table и arrow_table.

Примечание: Массив NumPy является допустимой последовательностью последовательностей и может использоваться как аргумент data для основного метода insert, поэтому специализированный метод не требуется.

Вставка из файла

Модуль clickhouse_connect.driver.tools включает метод insert_file, позволяющий вставлять данные непосредственно из файловой системы в существующую таблицу ClickHouse. Парсинг делегируется серверу ClickHouse. Метод insert_file принимает следующие параметры:

Параметр	Тип	По умолчанию	Описание
client	Client	Обязательный	Экземпляр driver.Client, используемый для выполнения вставки.
table	str	Обязательный	Таблица ClickHouse, в которую осуществляется вставка. Допускается полное имя таблицы (включая базу данных).
file_path	str	Обязательный	Путь к файлу данных в нативной файловой системе
fmt	str	CSV, CSVWithNames	Формат ввода ClickHouse для файла. Предполагается CSVWithNames, если column_names не указан.
column_names	Последовательность str	Нет	Список имен колонок в файле данных. Не требуется для форматов, включающих имена колонок.
database	str	Нет	База данных таблицы. Игнорируется, если таблица полностью квалифицирована. Если не указана, будет использоваться база данных клиента.
settings	dict	Нет	См. описание настроек.
compression	str	Нет	Принятый тип сжатия ClickHouse (zstd, lz4, gzip), используемый для заголовка Content-Encoding HTTP.

Для файлов с неконсистентными данными или значениями даты/времени в необычном формате, настройки, применимые к импорту данных (такие как input_format_allow_errors_num и input_format_allow_errors_ratio), распознаются для этого метода.

Сохранение результатов запроса в файлы

Вы можете потоково сохранять файлы непосредственно из ClickHouse в локальную файловую систему, используя метод raw_stream. Например, если вы хотите сохранить результаты запроса в CSV-файл, вы можете использовать следующий фрагмент кода:

Код выше создает файл output.csv со следующим содержимым:

Таким же образом, вы можете сохранить данные в TabSeparated и других форматах. См. Форматы для ввода и вывода данных для обзора всех доступных опций форматов.

Сырой API

Для случаев использования, которые не требуют преобразования между данными ClickHouse и нативными или сторонними типами и структурами данных, клиент ClickHouse Connect предоставляет два метода для прямого использования соединения ClickHouse.

Клиентский метод raw_query {#client-raw_query-method}

Метод Client.raw_query позволяет напрямую использовать HTTP интерфейс запросов ClickHouse с использованием соединения клиента. Возвращаемое значение - это необработанный объект bytes. Он предлагает удобный обертку с привязкой параметров, обработкой ошибок, повторными попытками и управлением настройками с минимальным интерфейсом:

Параметр	Тип	По умолчанию	Описание
query	str	Обязательный	Любой допустимый запрос ClickHouse
parameters	dict или iterable	Нет	См. описание параметров.
settings	dict	Нет	См. описание настроек.
fmt	str	Нет	Формат вывода ClickHouse для результирующих байтов. (ClickHouse использует TSV, если не указано)
use_database	bool	True	Использовать базу данных, назначенную клиенту clickhouse-connect, в контексте запроса
external_data	ExternalData	Нет	Объект ExternalData, содержащий файл или двоичные данные, которые будут использованы в запросе. См. Расширенные запросы (Внешние данные)

За обработку возвращаемого объекта bytes отвечает вызывающая сторона. Обратите внимание, что метод Client.query_arrow является просто тонкой оберткой вокруг этого метода, использующего формат вывода ClickHouse Arrow.

Клиентский метод raw_stream {#client-raw_stream-method}

Метод Client.raw_stream имеет тот же API, что и метод raw_query, но возвращает объект io.IOBase, который может использоваться как генератор/источник потока объектов bytes. В настоящее время он используется методом query_arrow_stream.

Клиентский метод raw_insert {#client-raw_insert-method}

Метод Client.raw_insert позволяет напрямую вставлять объекты bytes или генераторы объектов bytes с использованием соединения клиента. Поскольку он не выполняет обработку вставляемого полезного груза, его производительность очень высокая. Метод предоставляет опции для указания настроек и формата вставки:

Параметр	Тип	По умолчанию	Описание
table	str	Обязательный	Либо простое, либо полное квалифицированное имя таблицы
column_names	Последовательность[str]	Нет	Имена колонок для блока вставки. Обязательно, если параметр fmt не включает названия
insert_block	str, bytes, Генератор[bytes], BinaryIO	Обязательный	Данные для вставки. Строки будут закодированы с использованием кодировки клиента.
settings	dict	Нет	См. описание настроек.

На вызывающей стороне лежит ответственность за то, чтобы insert_block соответствовал указанному формату и использовал метод сжатия. ClickHouse Connect использует эти необработанные вставки для загрузки файлов и таблиц PyArrow, делегируя анализ серверу ClickHouse.

Утилитные классы и функции

Следующие классы и функции также считаются частью публичного API clickhouse-connect и, как и классы и методы, задокументированные выше, стабильны между незначительными выпусками. Изменения с нарушением совместимости для этих классов и функций произойдут только с незначительным (а не патчем) выпуском и будут доступны с пометкой устаревших как минимум на один незначительный выпуск.

Исключения

Все пользовательские исключения (включая те, что определены в спецификации DB API 2.0) определены в модуле clickhouse_connect.driver.exceptions. Исключения, фактически обнаруженные драйвером, будут использовать один из этих типов.

Утилиты Clickhouse SQL

Функции и класс DT64Param в модуле clickhouse_connect.driver.binding могут быть использованы для правильного построения и экранирования запросов SQL ClickHouse. Точно так же функции в модуле clickhouse_connect.driver.parser могут быть использованы для разбора имен типов данных ClickHouse.

Многопоточные, многоэтапные и асинхронные/событийные варианты использования

ClickHouse Connect хорошо работает в многопоточных, многоэтапных и асинхронных приложениях, управляемых циклами событий. Все обработки запросов и вставок происходят в одном потоке, поэтому операции, как правило, являются потокобезопасными. (Параллельная обработка некоторых операций на низком уровне может быть возможным будущим улучшением, чтобы преодолеть штраф за производительность одноименного потока, но даже в этом случае будет поддерживаться безопасность потоков).

Поскольку каждый запрос или вставка выполняет состояние в своем собственном объекте QueryContext или InsertContext, соответственно, эти вспомогательные объекты не являются потокобезопасными и не должны использоваться для разделения между несколькими потоками обработки. См. дополнительное обсуждение об объектах контекста в следующих разделах.

Кроме того, в приложении, в котором одновременно выполняются два или более запросов и/или вставок, следует учитывать два дополнительных момента. Во-первых, сессия ClickHouse, связанная с запросом/вставкой, и, во-вторых, пул соединений HTTP, используемый экземплярами клиента ClickHouse Connect.

Обертка AsyncClient

С версии 0.7.16 ClickHouse Connect предоставляет асинхронную обертку над обычным Client, так что возможно использовать клиент в среде asyncio.

Чтобы получить экземпляр AsyncClient, вы можете использовать фабричную функцию get_async_client, которая принимает те же параметры, что и стандартный get_client:

AsyncClient имеет те же методы с теми же параметрами, что и стандартный Client, но они являются сопрограммами, когда это применимо. Внутри эти методы из Client, выполняющие операции ввода-вывода, заключены в run_in_executor вызов.

Производительность многопоточности увеличится при использовании обертки AsyncClient, поскольку потоки выполнения и GIL будут освобождены, пока ожидаются операции ввода-вывода.

Примечание: в отличие от обычного Client, AsyncClient по умолчанию принуждает autogenerate_session_id быть False.

См. также: пример run_async.

Управление идентификаторами сессий ClickHouse

Каждый запрос ClickHouse выполняется в контексте "сессии" ClickHouse. Сессии в настоящее время используются для двух целей:

• Для связи конкретных настроек ClickHouse с несколькими запросами (см. настройки пользователей). Команда ClickHouse SET используется для изменения настроек для области пользовательской сессии.
• Для отслеживания временных таблиц

По умолчанию, каждый запрос, выполняемый с помощью экземпляра клиента ClickHouse Connect, использует один и тот же идентификатор сессии для включения данной функциональности сессии. То есть команды SET и работа с временными таблицами работают, как следует, при использовании одного клиента ClickHouse. Но, по замыслу, сервер ClickHouse не позволяет одновременно выполнять запросы в одной и той же сессии. Поэтому для приложения ClickHouse Connect, которое будет выполнять одновременно запросы, есть два варианта.

• Создайте отдельный экземпляр Client для каждого потока выполнения (поток, процесс или обработчик событий), который будет иметь свой собственный идентификатор сессии. Это обычно лучший подход, так как он сохраняет состояние сессии для каждого клиента.
• Используйте уникальный идентификатор сессии для каждого запроса. Это избегает проблемы совместной сессии в случаях, когда временные таблицы или общие настройки сессии не требуются. (Общие настройки также могут быть предоставлены при создании клиента, но они отправляются с каждым запросом и не связаны с сессией). Уникальный session_id можно добавить в словарь settings для каждого запроса, или вы можете отключить общую настройку autogenerate_session_id:

В этом случае ClickHouse Connect не отправит идентификатор сессии, и сервер ClickHouse сгенерирует случайный идентификатор сессии. Опять же, временные таблицы и настройки на уровне сессии будут недоступны.

Настройка пула соединений HTTP

ClickHouse Connect использует пулы соединений urllib3 для обработки нижнего уровня HTTP-соединения с сервером. По умолчанию все экземпляры клиента используют один и тот же пул соединений, что достаточно для большинства случаев. Этот пул по умолчанию поддерживает до 8 соединений HTTP Keep Alive с каждым сервером ClickHouse, используемым приложением.

Для крупных многопоточных приложений могут быть уместны отдельные пулы соединений. Индивидуальные пулы соединений могут быть предоставлены как аргумент ключевого слова pool_mgr основной функции clickhouse_connect.get_client:

Как показано в приведенном выше примере, клиенты могут использовать один и тот же менеджер пула, или для каждого клиента может быть создан отдельный менеджер пула. Для получения дополнительной информации о доступных вариантах при создании PoolManager смотрите в документации urllib3.

Запрос данных с ClickHouse Connect: Расширенное использование

QueryContexts

ClickHouse Connect выполняет стандартные запросы в рамках QueryContext. QueryContext содержит ключевые структуры, которые используются для построения запросов к базе данных ClickHouse, и конфигурацию, используемую для обработки результата в QueryResult или другую структуру данных ответа. Это включает сам запрос, параметры, настройки, форматы чтения и другие свойства.

QueryContext можно получить с помощью метода клиента create_query_context. Этот метод принимает те же параметры, что и основной метод запроса. Этот контекст запроса затем может быть передан методам query, query_df или query_np в качестве аргумента context вместо любых или всех других аргументов этих методов. Обратите внимание, что дополнительные аргументы, указанные для вызова метода, переопределят любые свойства QueryContext.

Наиболее очевидным случаем использования QueryContext является отправка одного и того же запроса с различными значениями связывающих параметров. Все значения параметров могут быть обновлены путем вызова метода QueryContext.set_parameters с помощью словаря, или любое одно значение может быть обновлено, вызвав QueryContext.set_parameter с нужной парой key, value.

Обратите внимание, что QueryContexts не являются потокобезопасными, но копию можно получить в многопоточной среде, вызвав метод QueryContext.updated_copy.

Потоковые запросы

Data Blocks

ClickHouse Connect обрабатывает все данные из основного метода query как поток блоков, полученных от сервера ClickHouse. Эти блоки передаются в пользовательском формате "Native" к ClickHouse и обратно. "Блок" — это просто последовательность колонок двоичных данных, где каждая колонка содержит равное количество значений данных заданного типа. (Как столбцовая база данных, ClickHouse хранит эти данные в аналогичной форме.) Размер блока, возвращаемого из запроса, определяется двумя установками пользователя, которые можно задать на нескольких уровнях (профиль пользователя, пользователь, сессия или запрос). Они следующие:

• max_block_size -- Ограничение на размер блока в строках. По умолчанию 65536.
• preferred_block_size_bytes -- Мягкое ограничение на размер блока в байтах. По умолчанию 1,000,0000.

Независимо от preferred_block_size_setting, каждый блок никогда не будет больше max_block_size строк. В зависимости от типа запроса фактические возвращаемые блоки могут быть любого размера. Например, запросы к распределенной таблице, охватывающей множество шардов, могут содержать более мелкие блоки, извлекаемые напрямую из каждого шарда.

При использовании одного из методов клиента query_*_stream результаты возвращаются по блокам. ClickHouse Connect загружает только один блок за раз. Это позволяет обрабатывать большие объемы данных, не загружая весь большой набор результатов в память. Обратите внимание, что приложение должно быть готово обрабатывать любое количество блоков, и размер каждого блока не может контролироваться.

HTTP Data Buffer for Slow Processing

Из-за ограничений протокола HTTP, если блоки обрабатываются с коэффициентом, значительно меньшим, чем потоковая передача данных сервером ClickHouse, сервер ClickHouse закроет соединение, что приведет к ошибке в потоке обработки. Некоторая часть этого может быть смягчена за счет увеличения размера буфера HTTP потоковой передачи (который по умолчанию составляет 10 мегабайт) с использованием общей настройки http_buffer_size. Большие значения http_buffer_size должны быть приемлемы в этой ситуации, если приложению доступно достаточное количество памяти. Данные в буфере хранятся в сжатом виде, если используется сжатие lz4 или zstd, так что использование этих типов сжатия увеличит общий доступный буфер.

StreamContexts

Каждый из методов query_*_stream (например, query_row_block_stream) возвращает объект ClickHouse StreamContext, который является объединенным контекстом/генератором Python. Вот базовое использование:

Обратите внимание, что попытка использовать StreamContext без оператора with вызовет ошибку. Использование контекста Python гарантирует, что поток (в данном случае, потоковая HTTP-ответа) будет правильно закрыт, даже если не все данные были потреблены и/или во время обработки возникла ошибка. Кроме того, StreamContexts можно использовать только один раз для потребления потока. Попытка использования StreamContext после его завершения приведет к возникновению ошибки StreamClosedError.

Вы можете использовать свойство source объекта StreamContext для доступа к родительскому объекту QueryResult, который включает имена и типы колонок.

Stream Types

Метод query_column_block_stream возвращает блок в виде последовательности данных колонок, хранящихся как нативные типы данных Python. Используя указанные выше запросы taxi_trips, возвращаемые данные будут список, где каждый элемент списка является другим списком (или кортежем), содержащим все данные для соответствующей колонки. Таким образом, block[0] будет кортежем, содержащим только строки. Форматы, ориентированные на колонку, чаще всего используются для выполнения агрегатных операций над всеми значениями в колонке, например, для суммирования общих тарифов.

Метод query_row_block_stream возвращает блок как последовательность строк, как в традиционной реляционной базе данных. Для поездок на такси возвращаемые данные будут списком, где каждый элемент списка представляет строку данных. Таким образом, block[0] будет содержать все поля (в порядке) для первой поездки на такси, block[1] будет содержать строку со всеми полями для второй поездки на такси и так далее. Результаты, ориентированные на строки, обычно используются для отображения или преобразовательных процессов.

Метод query_row_stream является удобным методом, который автоматически переходит к следующему блоку при итерации по потоку. В остальном он идентичен query_row_block_stream.

Метод query_np_stream возвращает каждый блок как двумерный массив NumPy. Внутренне массивы NumPy (обычно) хранятся как колонки, поэтому не требуются отдельные методы для строк или колонок. "Форма" массива NumPy будет выражена как (колонки, строки). Библиотека NumPy предоставляет много методов для манипуляции массивами NumPy. Обратите внимание, что если все колонки в запросе имеют один и тот же dtype NumPy, возвращаемый массив NumPy также будет иметь только один dtype, и его можно будет изменять/вращать без фактического изменения внутренней структуры.

Метод query_df_stream возвращает каждый блок ClickHouse как двумерный DataFrame Pandas. Вот пример, который показывает, что объект StreamContext может быть использован как контекст в отложенной форме (но только один раз).

Наконец, метод query_arrow_stream возвращает результат в формате ClickHouse ArrowStream как pyarrow.ipc.RecordBatchStreamReader, завернутый в StreamContext. Каждая итерация потока возвращает PyArrow RecordBlock.

Read Formats

Форматы чтения контролируют типы данных значений, возвращаемых из методов клиента query, query_np и query_df. (Методы raw_query и query_arrow не изменяют входные данные от ClickHouse, поэтому управление форматом не применяется.) Например, если формат чтения для UUID изменен с формата по умолчанию native на альтернативный формат string, запрос ClickHouse к колонке UUID будет возвращен как строковые значения (с использованием стандартного формата RFC 1422 8-4-4-4-12) вместо объектов Python UUID.

Аргумент "тип данных" для любой функции форматирования может включать подстановочные знаки. Формат — это одна строка в нижнем регистре.

Форматы чтения можно установить на нескольких уровнях:

• Глобально, используя методы, определенные в пакете clickhouse_connect.datatypes.format. Это будет контролировать формат настроенного типа данных для всех запросов.

• Для всего запроса, используя необязательный аргумент словаря query_formats. В этом случае любая колонка (или субколонка) указанных типов данных будет использовать настроенный формат.

• Для значений в конкретной колонке, используя необязательный аргумент словаря column_formats. Ключом является имя колонки, возвращаемое ClickHouse, и формат для колонки данных или вторичный словарь формата типа ClickHouse и значение форматов запроса. Этот вторичный словарь может использоваться для вложенных типов колонн, таких как кортежи или карты.

Read Format Options (Python Types)

ClickHouse Type	Native Python Type	Read Formats	Comments
Int[8-64], UInt[8-32]	int	-
UInt64	int	signed	Superset в настоящее время не обрабатывает большие ненастоящие значения UInt64
[U]Int[128,256]	int	string	Значения int Pandas и NumPy максимум 64 бита, так что они могут быть возвращены как строки
Float32	float	-	Все числа с плавающей точкой Python внутренне 64 бита
Float64	float	-
Decimal	decimal.Decimal	-
String	string	bytes	Строки ClickHouse не имеют внутреннего кодирования, поэтому они также используются для двоичных данных переменной длины
FixedString	bytes	string	FixedStrings — это массивы байт фиксированного размера, но иногда их обрабатывают как строки Python
Enum[8,16]	string	string, int	Python Enums не принимают пустые строки, поэтому все Enums рендерятся как строки или базовые значения int.
Date	datetime.date	int	ClickHouse хранит даты как дни с 01/01/1970. Это значение доступно как int
Date32	datetime.date	int	То же самое, что и Date, но для более широкого диапазона дат
DateTime	datetime.datetime	int	ClickHouse хранит DateTime в эпохе секундах. Это значение доступно как int
DateTime64	datetime.datetime	int	Python datetime.datetime ограничен точностью до микросекунд. Сырое 64-битное int значение доступно
IPv4	ipaddress.IPv4Address	string	IP-адреса могут быть прочитаны как строки, и правильно отформатированные строки могут быть вставлены как IP-адреса
IPv6	ipaddress.IPv6Address	string	IP-адреса могут быть прочитаны как строки, и правильно отформатированные могут быть вставлены как IP-адреса
Tuple	dict or tuple	tuple, json	Именованные кортежи возвращаются как словари по умолчанию. Именованные кортежи также могут возвращаться как JSON строки
Map	dict	-
Nested	Sequence[dict]	-
UUID	uuid.UUID	string	UUID могут быть прочитаны как строки, отформатированные в соответствии с RFC 4122
JSON	dict	string	По умолчанию возвращается словарь Python. Формат string вернет строку JSON
Variant	object	-	Возвращает соответствующий тип Python для типа данных ClickHouse, хранящегося для значения
Dynamic	object	-	Возвращает соответствующий тип Python для типа данных ClickHouse, хранящегося для значения

External Data

Запросы ClickHouse могут принимать внешние данные в любом формате ClickHouse. Эти двоичные данные отправляются вместе с строкой запроса, чтобы быть использованными для обработки данных. Подробности о функции внешних данных здесь. Методы клиента query* принимают необязательный параметр external_data для использования этой функции. Значение для параметра external_data должно быть объектом clickhouse_connect.driver.external.ExternalData. Конструктор этого объекта принимает следующие аргументы:

Name	Type	Description
file_path	str	Путь к файлу на локальной системе, из которого читать внешние данные. Либо file_path, либо data обязательны
file_name	str	Имя "файла" внешних данных. Если не указано, будет определено из file_path (без расширений)
data	bytes	Внешние данные в двоичном виде (вместо чтения из файла). Либо data, либо file_path обязательны
fmt	str	Формат ввода ClickHouse Input Format данных. По умолчанию TSV
types	str or seq of str	Список типов данных колонки во внешних данных. Если строка, типы должны быть разделены запятыми. Либо types, либо structure обязательны
structure	str or seq of str	Список имени колонки + типа данных в данных (см. примеры). Либо structure, либо types обязательны
mime_type	str	Необязательный MIME-тип данных файла. В настоящее время ClickHouse игнорирует этот заголовок HTTP

Чтобы отправить запрос с внешним CSV файлом, содержащим данные о "фильмах", и объединить эти данные с таблицей directors, уже присутствующей на сервере ClickHouse:

Дополнительные файлы внешних данных могут быть добавлены в первоначальный объект ExternalData с помощью метода add_file, который принимает те же параметры, что и конструктор. Для HTTP все внешние данные передаются как часть загрузки файла multi-part/form-data.

Time Zones

Существует несколько механизмов применения часового пояса к значениям ClickHouse DateTime и DateTime64. Внутренне сервер ClickHouse всегда хранит любой объект DateTime или DateTime64 как naivный номер времени, представляющий секунды с начала эпохи, 1970-01-01 00:00:00 UTC. Для значений DateTime64 это представление может быть миллисекундами, микросекундами или наносекундами с начала эпохи, в зависимости от точности. В результате применение любой информации о часовом поясе всегда происходит на стороне клиента. Обратите внимание, что это требует значительных дополнительных вычислений, поэтому в приложениях с критичной производительностью рекомендуется относиться к типам DateTime как к временным меткам эпохи, за исключением отображения пользователю и преобразования (например, метки времени Pandas всегда являются 64-битными целыми числами, представляющими наносекунды эпохи, чтобы повысить производительность).

При использовании типов данных, учитывающих часовые пояса, в запросах — в частности, объекта Python datetime.datetime -- clickhouse-connect применяет часовую зону на стороне клиента, используя следующие правила приоритета:

1. Если параметр метода запроса client_tzs указан для запроса, применяется конкретная временная зона колонки.
2. Если колонка ClickHouse имеет метаданные часового пояса (т.е. она является типом, как DateTime64(3, 'America/Denver')), применяется часовой пояс колонки ClickHouse. (Обратите внимание, что эти метаданные часового пояса не доступны для clickhouse-connect для колонок DateTime до версии ClickHouse 23.2)
3. Если параметр метода запроса query_tz указан для запроса, применяется "часовая зона запроса".
4. Если к запросу или сессии применяется настройка часового пояса, применяется этот часовой пояс. (Эта функциональность еще не выпущена в сервере ClickHouse)
5. Наконец, если параметр клиента apply_server_timezone установлен в True (по умолчанию), применяется часовой пояс сервера ClickHouse.

Обратите внимание, что если применяемый часовой пояс по этим правилам — UTC, clickhouse-connect всегда вернет naivный объект Python datetime.datetime. Дополнительную информацию о часовом поясе затем можно добавить к этому naiv объекту почасовому коду, если это необходимо.

Inserting Data with ClickHouse Connect: Advanced Usage

InsertContexts

ClickHouse Connect выполняет все вставки в рамках InsertContext. InsertContext включает все значения, отправляемые в качестве аргументов методу клиента insert. Кроме того, когда InsertContext изначально создается, ClickHouse Connect извлекает типы данных для колонок вставки, необходимые для эффективных вставок в формате Native. Повторное использование InsertContext для нескольких вставок позволяет избежать этого "препроекта" и выполнять вставки быстрее и эффективнее.

InsertContext можно получить, используя метод клиента create_insert_context. Этот метод принимает те же аргументы, что и функция insert. Обратите внимание, что изменять следует только свойство data InsertContext для повторного использования. Это согласуется с его назначением предоставления повторно используемого объекта для многократных вставок новых данных в ту же таблицу.

InsertContexts включают изменяемое состояние, которое обновляется в процессе вставки, поэтому они не безопасны для потоков.

Write Formats

Форматы записи в настоящее время реализованы для ограниченного числа типов. В большинстве случаев ClickHouse Connect будет пытаться автоматически определить правильный формат записи для колонки, проверяя тип первого (ненулевого) значения данных. Например, если вставляется в колонку DateTime, и первое вставляемое значение колонки является целым числом Python, ClickHouse Connect напрямую вставит это целое число, предполагая, что это фактически эпоха в секундах.

В большинстве случаев нет необходимости переопределять формат записи для типа данных, но соответствующие методы в пакете clickhouse_connect.datatypes.format могут быть использованы для этого на глобальном уровне.

Write Format Options

ClickHouse Type	Native Python Type	Write Formats	Comments
Int[8-64], UInt[8-32]	int	-
UInt64	int
[U]Int[128,256]	int
Float32	float
Float64	float
Decimal	decimal.Decimal
String	string
FixedString	bytes	string	Если вставляется как строка, дополнительные байты будут установлены в нули
Enum[8,16]	string
Date	datetime.date	int	ClickHouse хранит даты как дни с 01/01/1970. Типы int будут считаться значением "даты эпохи"
Date32	datetime.date	int	То же самое, что и Date, но для более широкого диапазона дат
DateTime	datetime.datetime	int	ClickHouse хранит DateTime в эпохе секундах. Типы int будут считаться значением "второй эпохи"
DateTime64	datetime.datetime	int	Python datetime.datetime ограничен точностью до микросекунд. Значение сырых 64 бит доступно
IPv4	ipaddress.IPv4Address	string	Правильно отформатированные строки могут быть вставлены как IP-адреса
IPv6	ipaddress.IPv6Address	string	Правильно отформатированные строки могут быть вставлены как IP-адреса
Tuple	dict or tuple
Map	dict
Nested	Sequence[dict]
UUID	uuid.UUID	string	Правильно отформатированные строки могут быть вставлены как UUID ClickHouse
JSON/Object('json')	dict	string	В JSON-колонки могут быть вставлены как словари, так и JSON-строки (заметьте, что Object('json') устарело)
Variant	object		В настоящее время все варианты вставляются как строки и разбираются сервером ClickHouse
Dynamic	object		Внимание -- в настоящее время любые вставки в динамическую колонку сохраняются как строка ClickHouse

Additional Options

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

Global Settings

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

примечание

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

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

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

Сжатие

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-коде, поэтому производительность может быть несколько ниже, чем для более простых, устоявшихся типов данных.