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

Введение

ClickHouse Connect — это основной драйвер базы данных, обеспечивающий взаимодействие с широким спектром приложений на Python.

• Основной интерфейс — это объект Client в пакете clickhouse_connect.driver. Этот основной пакет также включает различные вспомогательные классы и утилиты, используемые для общения с сервером ClickHouse и реализации "контекста" для продвинутого управления запросами вставки и выборки.
• Пакет clickhouse_connect.datatypes предоставляет базовую реализацию и подклассы для всех неэкспериментальных типов данных ClickHouse. Его основная функциональность заключается в сериализации и десериализации данных ClickHouse в двоичный колоночный формат "Native", используемый для достижения наиболее эффективной передачи между ClickHouse и клиентскими приложениями.
• Cython/C классы в пакете clickhouse_connect.cdriver оптимизируют некоторые из наиболее распространенных сериализаций и десериализаций для значительного улучшения производительности по сравнению с чистым Python.
• В пакете clickhouse_connect.cc_sqlalchemy есть ограниченный диалект SQLAlchemy, который построен на основе пакетов datatypes и dbi. Эта ограниченная реализация сосредоточена на функциональности запросов/курсов, и не поддерживает операции DDL и ORM SQLAlchemy. (SQLAlchemy нацелена на OLTP базы данных, и мы рекомендуем более специализированные инструменты и фреймворки для управления базой данных ClickHouse, ориентированной на OLAP.)
• Основной драйвер и реализация ClickHouse Connect SQLAlchemy являются предпочтительными методами для подключения ClickHouse к Apache Superset. Используйте ClickHouse Connect для подключения к базе данных или строку подключения clickhousedb для диалекта SQLAlchemy.

Эта документация актуальна на момент бета-релиза 0.8.2.

примечание

Официальный драйвер ClickHouse Connect для Python использует протокол HTTP для связи с сервером ClickHouse. У него есть некоторые преимущества (такие как лучшая гибкость, поддержка HTTP-балансировщиков, лучшее взаимодействие с инструментами на базе JDBC и т.д.) и недостатки (такие как чуть более низкое сжатие и производительность, а также отсутствие поддержки некоторых сложных функций родного TCP-протокола). Для некоторых сценариев вы можете рассмотреть возможность использования одного из Community Python драйверов, который использует родной TCP-протокол.

Требования и совместимость

Python		Платформа¹		ClickHouse		SQLAlchemy²		Apache Superset
2.x, <3.8	❌	Linux (x86)	✅	<24.3³	🟡	<1.3	❌	<1.4	❌
3.8.x	✅	Linux (Aarch64)	✅	24.3.x	✅	1.3.x	✅	1.4.x	✅
3.9.x	✅	macOS (x86)	✅	24.4-24.6³	🟡	1.4.x	✅	1.5.x	✅
3.10.x	✅	macOS (ARM)	✅	24.7.x	✅	>=2.x	❌	2.0.x	✅
3.11.x	✅	Windows	✅	24.8.x	✅			2.1.x	✅
3.12.x	✅			24.9.x	✅			3.0.x	✅

¹ClickHouse Connect был явно протестирован на перечисленных платформах. Кроме того, непроверенные бинарные колеса (с оптимизацией C) создаются для всех архитектур, поддерживаемых отличным проектом cibuildwheel. Наконец, поскольку ClickHouse Connect также может работать в чистом Python, установка из исходных кодов должна работать на любой новой установке Python.

²Поддержка SQLAlchemy также ограничена в основном функциональностью запросов. Полный API SQLAlchemy не поддерживается.

³ClickHouse Connect был протестирован на всех текущих поддерживаемых версиях ClickHouse. Поскольку он использует протокол HTTP, он также должен работать правильно для большинства других версий ClickHouse, хотя могут быть некоторые несовместимости с определенными расширенными типами данных.

Установка

Установите ClickHouse Connect из PyPI через pip:

pip install clickhouse-connect

ClickHouse Connect также можно установить из исходников:

• git clone репозиторий GitHub.
• (По желанию) выполните pip install cython, чтобы собрать и включить оптимизации C/Cython.
• cd в корневую директорию проекта и выполните pip install .

Политика поддержки

ClickHouse Connect в настоящее время находится в бета-версии и только текущий бета-релиз активно поддерживается. Пожалуйста, обновите до последней версии перед тем, как сообщить о каких-либо проблемах. Проблемы следует сообщать в проект GitHub. Будущие релизы ClickHouse Connect гарантированно будут совместимы с активно поддерживаемыми версиями ClickHouse на момент релиза (обычно три последние версии stable и две последние версии lts).

Основное использование

Соберите свои данные для подключения

Чтобы подключиться к ClickHouse с помощью HTTP(S), вам нужна следующая информация:

• ХОСТ и ПОРТ: обычно порт 8443 при использовании TLS или 8123 при его отсутствии.

• НАЗВАНИЕ БАЗЫ ДАННЫХ: по умолчанию есть база данных с именем default, используйте имя базы данных, к которой вы хотите подключиться.

• ИМЯ ПОЛЬЗОВАТЕЛЯ и ПАРОЛЬ: по умолчанию имя пользователя default. Используйте имя пользователя, подходящее для вашего случая использования.

Данные для вашей службы ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите службу, к которой вы будете подключаться, и нажмите Подключиться:

Выберите HTTPS, и детали будут доступны в примере команды curl.

Если вы используете self-managed ClickHouse, детали подключения задаются вашим администратором ClickHouse.

Установите подключение

Приведены два примера подключения к ClickHouse:

• Подключение к серверу ClickHouse на localhost.
• Подключение к облачному сервису ClickHouse.

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

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

подсказка

Используйте данные подключения, собранные ранее. Облачные сервисы ClickHouse требуют 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	Порт HTTP или HTTPS ClickHouse. Если не указано, по умолчанию будет 8123, или 8443, если secure=True или interface=https.
username	str	default	Имя пользователя ClickHouse. Если не указано, используется пользователь default ClickHouse.
password	str	<пустая строка>	Пароль для username.
database	str	None	База данных по умолчанию для подключения. Если не указано, ClickHouse Connect будет использовать базу данных по умолчанию для username.
secure	bool	False	Использовать https/TLS. Это переопределяет выводимые значения из аргументов interface или port.
dsn	str	None	Строка в стандартном формате DSN (Имя источника данных). Другие значения подключения (такие как host или user) будут извлечены из этой строки, если не указано иное.
compress	bool or str	True	Включить сжатие для вставок и результатов запросов ClickHouse HTTP. См. Дополнительные параметры (Сжатие)
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.query_log.
pool_mgr	obj	<default PoolManager>	PoolManager библиотеки 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 предполагает взаимную аутентификацию TLS ClickHouse с сертификатом клиента. None/поведение по умолчанию — это mutual

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

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

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

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

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

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

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

• Подключение с id сессии и другими пользовательскими параметрами подключения и настройками 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 с точностью до подсекунды) требуется один из двух пользовательских подходов:

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

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

Все ключевые методы ClickHouse Connect Client "insert" и "select" принимают дополнительный аргумент 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	Использовать базу данных клиента (установленную при создании клиента). False означает, что команда будет использовать базу данных по умолчанию сервера 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. Он использует нативный формат ClickHouse через HTTP для эффективной передачи больших наборов данных (до примерно одного миллиона строк). Этот метод принимает следующие параметры.

Параметр	Тип	По умолчанию	Описание
query	str	Обязательный	Запрос ClickHouse SQL SELECT или DESCRIBE.
parameters	dict или итерируемый объект	Нет	Смотрите описание параметров.
settings	dict	Нет	Смотрите описание настроек.
query_formats	dict	Нет	Спецификация форматирования типов данных для значений результата. Смотрите Расширенное использование (Чтение форматов)
column_formats	dict	Нет	Форматирование типов данных по колонкам. Смотрите Расширенное использование (Чтение форматов)
encoding	str	Нет	Кодировка, используемая для преобразования строковых колонок ClickHouse в строки Python. Python по умолчанию использует UTF-8, если не указано.
use_none	bool	True	Использовать тип Python None для значений NULL ClickHouse. Если False, использовать значение по умолчанию типа данных (например, 0) для значений NULL ClickHouse. Обратите внимание - по умолчанию False для NumPy/Pandas по соображениям производительности.
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, который можно использовать для инкапсуляции указанных выше аргументов метода. Смотрите Расширенные запросы (Контекст запросов)

Объект QueryResult

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

• result_rows -- Матрица данных, возвращаемых в форме последовательности строк, где каждый элемент строки является последовательностью значений колонок.
• result_columns -- Матрица данных, возвращаемых в форме последовательности колонок, где каждый элемент колонки является последовательностью значений строки для этой колонки.
• column_names -- Кортеж строк, представляющий названия колонок в result_set.
• column_types -- Кортеж экземпляров ClickHouseType, представляющих тип данных ClickHouse для каждой колонки в result_columns.
• query_id -- Идентификатор запроса ClickHouse (полезно для проверки запроса в таблице 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, который можно использовать как итератор для возвращаемых данных. К ним следует обращаться только косвенно, используя методы *_stream клиента.

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

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

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

• query_np -- Эта версия возвращает массив NumPy вместо объекта QueryResult ClickHouse Connect.
• query_df -- Эта версия возвращает датафрейм Pandas вместо объекта QueryResult ClickHouse Connect.
• query_arrow -- Эта версия возвращает таблицу PyArrow. Она использует формат Arrow ClickHouse напрямую, поэтому принимает только три аргумента, схожих с основным методом query: query, parameters и settings. Кроме того, есть дополнительный аргумент use_strings, который определяет, будет ли таблица Arrow отображать типы строк 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 в виде датафрейма Pandas.
• query_arrow_stream -- Возвращает данные запроса в форматах PyArrow RecordBlocks.

Каждый из этих методов возвращает объект 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, который должен быть экземпляром датафрейма Pandas. ClickHouse Connect автоматически обрабатывает датафрейм как источник данных с колоночной ориентацией, поэтому параметр column_oriented не требуется и недоступен.
• insert_arrow -- Вместо аргумента data в виде Python последовательности последовательностей этот метод требует 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_num), распознаются для этого метода.

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

Вы можете непосредственно потоковые файлы из 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 или итерируемый объект	Нет	Смотрите описание параметров.
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	Нет	Смотрите описание настроек.
fmt	str	Нет	Формат ввода ClickHouse для байтов insert_block. (ClickHouse использует TSV, если не указано)

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

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

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

Исключения

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

SQL утилиты Clickhouse

Функции и классы 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. Обратите внимание, что если все колонки в запросе имеют одинаковый тип данных NumPy, возвращаемый массив NumPy также будет иметь только один тип данных и может быть преобразован/поворотить без фактического изменения его внутренней структуры.

Метод 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	Значения целых чисел в 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 Enum не принимает пустые строки, поэтому все Enums будут отображаться либо как строки, либо как соответствующее целое значение.
Date	datetime.date	int	ClickHouse хранит даты как дни с 01/01/1970. Это значение доступно как целое число
Date32	datetime.date	int	То же самое, что и для Date, но для более широкого диапазона дат
DateTime	datetime.datetime	int	ClickHouse хранит DateTime в секундах с начала эпохи. Это значение доступно как целое число
DateTime64	datetime.datetime	int	python datetime.datetime ограничен точностью в микросекундах. Доступно сырой 64-битное целое значение
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 как число, не зависящее от часового пояса, представляющее секунды с начала эпохи, 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 всегда вернет объект Python datetime.datetime, не зависящий от часового пояса. Дополнительная информация о часовом поясе может быть добавлена к этому объекту, не зависящему от часового пояса, кодом приложения, если это необходимо.

Inserting Data with ClickHouse Connect: Advanced Usage

InsertContexts

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

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

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. Для целых типов будут предполагаться значения этой "эпохи"
Date32	datetime.date	int	То же самое, что и для Date, но для более широкого диапазона дат
DateTime	datetime.datetime	int	ClickHouse хранит DateTime в секундах эпохи. Для целых типов будут предполагаться значения этой "эпохи"
DateTime64	datetime.datetime	int	datetime.datetime Python ограничены точностью в микросекундах. Доступно сырое 64-битное целое значение
IPv4	ipaddress.IPv4Address	string	Правильно отформатированные строки могут быть вставлены как адреса IPv4
IPv6	ipaddress.IPv6Address	string	Правильно отформатированные строки могут быть вставлены как адреса IPv6
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, будет вызвана ошибка программирования на стороне клиента.
dict_parameter_format	'json'	'json', 'map'	Это управляет тем, преобразуются ли параметризованные запросы из Python-словаря в JSON или синтаксис ClickHouse Map. Используйте json для вставок в JSON-колонки, map для колонок ClickHouse Map.
product_name			Строка, которая передается с запросом в ClickHouse для отслеживания приложения, использующего ClickHouse Connect. Должна быть в формате <product name;&gl/<product version>
max_connection_age	600		Максимальное количество секунд, в течение которых будет поддерживаться/повторно использовать соединение HTTP Keep Alive. Это предотвращает сгруппировку соединений против одного узла ClickHouse за балансировщиком нагрузки/прокси. По умолчанию 10 минут.
readonly	0	0, 1	Предполагаемые настройки ClickHouse "только для чтения" для версий до 19.17. Может быть установлено для соответствия значению "только для чтения" ClickHouse, чтобы разрешать операции с очень старыми версиями ClickHouse.
use_protocol_version	True	True, False	Используйте версию клиентского протокола. Это необходимо для колонок временных меток, но нарушает работу с текущей версией chproxy.
max_error_size	1024		Максимальное количество символов, которые будут возвращены в сообщениях об ошибке клиента. Используйте 0 для этой настройки, чтобы получить полное сообщение об ошибке ClickHouse. По умолчанию 1024 символа.
send_os_user	True	True, False	Включить определенное имя пользователя операционной системы в информации клиента, отправляемой в ClickHouse (HTTP User-Agent строка).
http_buffer_size	10MB		Размер (в байтах) "в памяти" буфера, используемого для запросов HTTP-потока.