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

Введение

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

• Основной интерфейс — это объект Client в пакете clickhouse_connect.driver. Этот основной пакет также включает разнообразные вспомогательные классы и утилиты, используемые для связи с сервером ClickHouse и реализации "контекста" для продвинутого управления запросами вставки и выборки.
• Пакет clickhouse_connect.datatypes предоставляет базовую реализацию и подклассы для всех непостоянных типов данных ClickHouse. Его основная функциональность заключается в сериализации и десериализации данных ClickHouse в "родной" двоичный столбцовый формат, который используется для обеспечения наиболее эффективной транспортировки между ClickHouse и клиентскими приложениями.
• Классы Cython/C в пакете clickhouse_connect.cdriver оптимизируют некоторые из наиболее распространённых сериализаций и десериализаций для значительно улучшенной производительности по сравнению с чистым Python.
• В пакете clickhouse_connect.cc_sqlalchemy присутствует ограниченный диалект SQLAlchemy, который построен на основе пакетов datatypes и dbi. Эта ограниченная реализация сосредотачивается на функциональности запроса/курсора и обычно не поддерживает операции SQLAlchemy DDL и ORM. (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-протокола). Для некоторых случаев использования вы можете рассмотреть возможность использования одного из 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.
• Перейдите в корневой каталог проекта и выполните pip install .

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

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

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

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

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

• ХОСТ и ПОРТ: как правило, порт составляет 8443 при использовании TLS или 8123 при отсутствии TLS.

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

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

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

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

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

Установите соединение

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

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

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

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

подсказка

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

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

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

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

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

API драйвера ClickHouse Connect

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

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

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

Класс clickhouse_connect.driver.client предоставляет основной интерфейс между Python приложением и сервером базы данных ClickHouse. Используйте функцию clickhouse_connect.get_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. Это переопределяет выводимые значения из аргументов interface или port.
dsn	str	None	Строка в стандартном формате DSN (Data Source Name). Другие значения подключения (такие как host или user) будут извлечены из этой строки, если не указаны иным образом.
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 предполагает взаимное TLS-аутентификацию ClickHouse с сертификатом клиента. Поведение по умолчанию – 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 и escaping строки

• Пример с помощью последовательности 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 или iterable	None	См. описание параметров.
data	str или 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. Он использует формат Native ClickHouse через HTTP для эффективной передачи больших наборов данных (до примерно миллиона строк). Этот метод принимает следующие параметры.

Параметр	Тип	По умолчанию	Описание
query	str	Обязательно	SQL-запрос ClickHouse SELECT или DESCRIBE.
parameters	dict или iterable	Нет	См. описание параметров.
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. Заметьте, что по умолчанию для 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 -- 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, который может быть использован в качестве итератора для возвращаемых данных. Они должны быть доступны только косвенно, используя методы Client *_stream.

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

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

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

• query_np -- Эта версия возвращает массив NumPy вместо QueryResult подключения ClickHouse.
• query_df -- Эта версия возвращает Dataframe Pandas вместо QueryResult подключения ClickHouse.
• query_arrow -- Эта версия возвращает таблицу PyArrow. Она использует формат ClickHouse Arrow напрямую, поэтому принимает только три аргумента, общие с основным методом 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 в виде Dataframe 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, который должен быть экземпляром DataFrame Pandas. ClickHouse Connect автоматически обрабатывает DataFrame как источник данных, ориентированный на столбцы, поэтому параметр column_oriented не требуется и недоступен.
• insert_arrow -- Вместо 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), используемый для заголовка HTTP Content-Encoding

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

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

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

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

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

Raw 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	Нет	См. описание настроек.
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 с несколькими запросами (см. настройки пользователей). Команда SET ClickHouse используется для изменения настроек в рамках сеансов пользователя.
• Для отслеживания временных таблиц.

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

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

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

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

ClickHouse Connect использует пулы соединений urllib3 для обработки основного HTTP-соединения с сервером. По умолчанию все экземпляры клиента разделяют один и тот же пул соединений, что достаточно для большинства случаев использования. Этот пул по умолчанию поддерживает до 8 HTTP-соединений на основе устаревших соединений к каждому серверу 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, каждый блок никогда не будет содержать более 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.

Read Formats

Форматы чтения контролируют типы данных значений, возвращаемых из клиентских методов query, query_np и query_df. (Методы raw_query и query_arrow не изменяют входные данные из ClickHouse, поэтому контроль формата не применяется.) Например, если формат чтения для UUID изменяется с формата по умолчанию native на альтернативный формат string, запрос ClickHouse по столбцу UUID будет возвращен как строковые значения (с использованием стандартного формата 8-4-4-4-12 RFC 1422) вместо объектов 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	Суперсеты в настоящее время не обрабатывают большие беззнаковые значения UInt64
[U]Int[128,256]	int	string	Значения int в Pandas и NumPy имеют максимум 64 бита, поэтому их можно вернуть как строки
Float32	float	-	Все Python float имеют 64 бита внутренне
Float64	float	-
Decimal	decimal.Decimal	-
String	string	bytes	Столбцы строк ClickHouse не имеют внутреннего кодирования, поэтому они также используются для данных переменной длины
FixedString	bytes	string	FixedStrings — это массивы байтов фиксированного размера, но иногда их обрабатывают как строки Python
Enum[8,16]	string	string, int	Python enums не принимают пустые строки, поэтому все 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 все внешние данные передаются как часть многокомпонентной формы загрузки файла.

Time Zones

Существуют разные механизмы для применения временной зоны к значениям DateTime и DateTime64 в ClickHouse. Внутри сервер 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. (Обратите внимание, что эта метадата временной зоны недоступна для столбцов 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	Python datetime.datetime ограничен микросекундной точностью. Доступно неформатированное 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, будет вызвано исключение ProgrammingError на стороне клиента
dict_parameter_format	'json'	'json', 'map'	Это контролирует, будут ли параметризованные запросы преобразовывать словарь Python в JSON или синтаксис карты ClickHouse. 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 "read_only" для версий до 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 потоковых запросов