Интеграция 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 базы данных, и мы рекомендуем использовать более специализированные инструменты и фреймворки для управления OLAP-ориентированной базой данных ClickHouse.) - Основной драйвер и реализация ClickHouse Connect SQLAlchemy являются предпочтительными методами для подключения ClickHouse к Apache Superset. Используйте строку подключения к базе данных
ClickHouse Connect
илиclickhousedb
диалекта SQLAlchemy.
Эта документация актуальна по состоянию на бета-версию 0.8.2.
Официальный драйвер Python ClickHouse Connect использует 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 на момент релиза (обычно три самых последних stable
и две самых последних lts
версии).
Основное использование
Подготовьте свои данные для подключения
Чтобы подключиться к ClickHouse с помощью HTTP(S), вам необходима следующая информация:
-
ХОСТ и ПОРТ: как правило, порт 8443 при использовании TLS или 8123 при отсутствии TLS.
-
ИМЯ БАЗЫ ДАННЫХ: по умолчанию существует база данных с именем
default
, используйте имя базы данных, к которой вы хотите подключиться. -
ИМЯ ПОЛЬЗОВАТЕЛЯ и ПАРОЛЬ: по умолчанию имя пользователя
default
. Используйте имя пользователя, подходящее для вашего случая.
Данные для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите сервис, к которому вы хотите подключиться, и нажмите Подключиться:

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

Если вы используете самоуправляемый 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 | Порт ClickHouse HTTP или HTTPS. Если не установлен, по умолчанию используется 8123 или 8443, если secure=True или interface=https. |
username | str | default | Имя пользователя ClickHouse. Если не установлено, будет использован пользователь ClickHouse по умолчанию default . |
password | str | <пустая строка> | Пароль для username. |
database | str | None | База данных по умолчанию для соединения. Если не установлено, ClickHouse Connect будет использовать базу данных по умолчанию для username. |
secure | bool | False | Использовать https/TLS. Это переопределяет выводимые значения из аргументов интерфейса или порта. |
dsn | str | None | Строка в стандартном формате DSN (Data Source Name). Другие значения соединения (такие как хост или пользователь) будут извлечены из этой строки, если не установлены иным образом. |
compress | bool или str | True | Включить сжатие для HTTP вставок ClickHouse и результатов запросов. См. Дополнительные параметры (Сжатие) |
query_limit | int | 0 (без ограничений) | Максимальное количество строк, которые следует вернуть для любого ответа на query . Установите это значение в ноль, чтобы вернуть неограниченное количество строк. Обратите внимание, что большие лимиты запросов могут привести к исключениям нехватки памяти, если результаты не передаются по потокам, так как все результаты загружаются в память сразу. |
query_retries | int | 2 | Максимальное количество повторных попыток для запроса query . Только "повторяемые" HTTP-ответы будут повторены. Запросы command или insert не повторяются автоматически драйвером, чтобы предотвратить непреднамеренные повторные запросы. |
connect_timeout | int | 10 | Таймаут подключения HTTP в секундах. |
send_receive_timeout | int | 300 | Таймаут отправки/получения для HTTP-соединения в секундах. |
client_name | str | None | client_name, добавленное к заголовку HTTP User Agent. Установите это значение, чтобы отслеживать клиентские запросы в системном журнале ClickHouse. |
pool_mgr | obj | <менеджер пула по умолчанию> | Менеджер пула urllib3 , который нужно использовать. Для более сложных случаев использования, требующих нескольких пулов соединения для разных хостов. |
http_proxy | str | None | Адрес HTTP-прокси (эквивалентно установке переменной окружения HTTP_PROXY). |
https_proxy | str | None | Адрес HTTPS-прокси (эквивалентно установке переменной окружения HTTPS_PROXY). |
apply_server_timezone | bool | True | Использовать серверный часовой пояс для учитываемых запросов с результатами. См. Приоритет часовых поясов |
Аргументы HTTPS/TLS
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
verify | bool | True | Проверить сертификат TLS/SSL сервера ClickHouse (имя хоста, срок действия и т.д.) при использовании HTTPS/TLS. |
ca_cert | str | None | Если verify=True, путь к файлу корневого сертификата Центра сертификации для проверки сертификата сервера ClickHouse в формате .pem. Игнорируется, если verify равно False. Это не обязательно, если сертификат сервера ClickHouse является глобально доверенным корнем, как это подтверждается операционной системой. |
client_cert | str | None | Путь к файлу клиентского сертификата TLS в формате .pem (для взаимной аутентификации TLS). Файл должен содержать полный цепь сертификатов, включая любые промежуточные сертификаты. |
client_cert_key | str | None | Путь к закрытому ключу для клиентского сертификата. Требуется, если закрытый ключ не включен в файл ключа клиентского сертификата. |
server_host_name | str | None | Имя хоста сервера ClickHouse, определенное CN или SNI его сертификата TLS. Установите это, чтобы избежать ошибок SSL при подключении через прокси или туннель с другим именем хоста |
tls_mode | str | None | Управляет расширенным поведением TLS. proxy и strict не вызывают взаимное TLS соединение ClickHouse, но отправляют клиентский сертификат и ключ. mutual предполагает взаимную аутентификацию TLS ClickHouse с клиентским сертификатом. Переопределение значений None/по умолчанию — это mutual |
Аргументы настроек
Наконец, аргумент settings
для get_client
используется для передачи дополнительных настроек ClickHouse серверу для каждого запроса клиента. Обратите внимание, что в большинстве случаев пользователи с доступом readonly=1 не могут изменять настройки, отправленные с запросом, поэтому ClickHouse Connect удалит такие настройки в окончательном запросе и запишет предупреждение. Следующие настройки применяются только к HTTP запросам/сессиям, используемым ClickHouse Connect, и не документируются как общие настройки ClickHouse.
Настройка | Описание |
---|---|
buffer_size | Размер буфера (в байтах), используемый сервером ClickHouse перед записью в HTTP-канал. |
session_id | Уникальный идентификатор сессии для ассоциации связанных запросов на сервере. Обязателен для временных таблиц. |
compress | Должен ли сервер ClickHouse сжимать данные ответа POST. Это значение следует использовать только для "сырьевых" запросов. |
decompress | Нужно ли данные, отправленные на сервер ClickHouse, разжать. Эта настройка должна использоваться только для "сырьевых" вставок. |
quota_key | Ключ квоты, связанный с этим запросом. См. документацию по квотам сервера ClickHouse. |
session_check | Используется для проверки статуса сессии. |
session_timeout | Количество секунд бездействия, после которого идентификатор сессии станет недействительным. По умолчанию 60 секунд. |
wait_end_of_query | Буферизует весь ответ на сервере ClickHouse. Эта настройка необходима для возврата итоговой информации и автоматически устанавливается для непотоковых запросов. |
Для других настроек ClickHouse, которые могут быть отправлены с каждым запросом, смотрите документацию ClickHouse.
Примеры создания клиента
- Без каких-либо параметров клиент ClickHouse Connect подключится к порту HTTP по умолчанию на
localhost
с пользователем по умолчанию и без пароля:
- Подключение к безопасному (https) внешнему серверу ClickHouse
- Подключение с идентификатором сеанса и другими пользовательскими параметрами подключения и настройками ClickHouse.
Общие аргументы методов
Несколько методов клиента используют один или оба общих аргумента parameters
и settings
. Эти аргументы по ключам описаны ниже.
Аргумент параметров
Методы ClickHouse Connect Client query*
и command
принимают необязательный аргумент ключевого слова parameters
, используемый для связывания выражений Python с выражением значения ClickHouse. Доступно два типа связывания.
Связывание на стороне сервера
ClickHouse поддерживает связь на стороне сервера для большинства значений запросов, где связываемое значение отправляется отдельно от запроса как параметр HTTP-запроса. ClickHouse Connect добавит соответствующие параметры запроса, если обнаружит выражение связывания формы
{<name>:<datatype>}
. Для связывания на стороне сервера аргумент parameters
должен быть словарем Python.
- Связь на стороне сервера с использованием словаря Python, значения DateTime и строкового значения
ВАЖНО — Связывание на стороне сервера поддерживается (сервером ClickHouse) только для запросов SELECT
. Оно не работает для запросов ALTER
, DELETE
, INSERT
или других типов запросов. Это может измениться в будущем, смотрите https://github.com/ClickHouse/ClickHouse/issues/42092.
Связывание на стороне клиента
ClickHouse Connect также поддерживает связывание параметров на стороне клиента, что может предоставить большую гибкость в генерации шаблонных SQL-запросов. Для связывания на стороне клиента аргумент parameters
должен быть словарем или последовательностью. Связывание на стороне клиента использует форматирование строк Python в стиле "printf" для замены параметров.
Обратите внимание, что, в отличие от связывания на стороне сервера, связывание на стороне клиента не работает для идентификаторов базы данных, таких как название базы данных, таблиц или колонок, поскольку форматирование в стиле Python не может различать разные типы строк, и их нужно форматировать по-разному (обратные кавычки или двойные кавычки для идентификаторов базы данных, одинарные кавычки для значений данных).
- Пример с использованием словаря Python, значения DateTime и экранирования строк
- Пример с использованием базы данных Python (Tuple), Float64 и IPv4Address
Для связывания аргументов DateTime64 (типы ClickHouse с точностью до субсекунд) требуется один из двух пользовательских подходов:
- Обернуть значение Python
datetime.datetime
в новый класс DT64Param, например,
- Если используете словарь значений параметров, добавьте строку
_64
к имени параметра
Аргумент настроек
Все ключевые методы клиента ClickHouse Connect "insert" и "select" принимают необязательный аргумент ключевого слова settings
, чтобы передать настройки пользователя ClickHouse настройки для данного SQL-запроса. Аргумент settings
должен быть словарем. Каждый элемент должен быть именем настройки ClickHouse и его соответствующим значением. Обратите внимание, что значения будут преобразованы в строки при отправке на сервер в качестве параметров запроса.
Как и для настроек уровня клиента, ClickHouse Connect удалит любые настройки, которые сервер помечает как readonly=1, с сообщением в журнале. Настройки, которые применяются только к запросам через HTTP-интерфейс ClickHouse, всегда действительны. Эти настройки описаны в API метода get_client
.
Пример использования настроек ClickHouse:
Метод клиента command
Используйте метод Client.command
, чтобы отправлять SQL-запросы на сервер ClickHouse, которые обычно не возвращают данные или возвращают одно простое значение или массив, а не полный набор данных. Этот метод принимает следующие параметры:
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
cmd | str | Обязательный | SQL-команда ClickHouse, которая возвращает единичное значение или одну строку значений. |
parameters | dict или iterable | None | См. описание параметров. |
data | str или bytes | None | Дополнительные данные, которые необходимо включить с командой в качестве тела POST-запроса. |
settings | dict | None | См. описание настроек. |
use_database | bool | True | Использовать клиентскую базу данных (указанную при создании клиента). Значение False означает, что команда будет использовать базу данных по умолчанию сервера ClickHouse для подключенного пользователя. |
external_data | ExternalData | None | Объект ExternalData, содержащий файлы или двоичные данные для использования с запросом. См. Расширенные запросы (Внешние данные) |
- command может быть использован для DDL операторов. Если SQL "command" не возвращает данные, возвращается вместо этого словарь "сводки запросов", который инкапсулирует заголовки ClickHouse X-ClickHouse-Summary и X-ClickHouse-Query-Id, включая пары ключ/значение
written_rows
,written_bytes
иquery_id
.
- command также может быть использован для простых запросов, которые возвращают только одну строку
Метод клиента query
Метод Client.query
является основным способом получения одного "пакета" набора данных с сервера ClickHouse. Он использует родной формат ClickHouse через HTTP для эффективной передачи больших наборов данных (до approximately одного миллиона строк). Этот метод принимает следующие параметры.
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
query | str | Обязательный | Запрос ClickHouse SQL SELECT или DESCRIBE. |
parameters | dict или iterable | None | См. описание параметров. |
settings | dict | None | См. описание настроек. |
query_formats | dict | None | Спецификация форматирования типов для значений результата. См. Расширенное использование (Чтение форматов) |
column_formats | dict | None | Форматирование типов для каждой колонки. См. Расширенное использование (Чтение форматов) |
encoding | str | None | Кодировка, используемая для кодирования строковых колонок ClickHouse в строках Python. Python по умолчанию использует UTF-8 , если не установлен. |
use_none | bool | True | Использовать тип Python None для ClickHouse null. Если False, использовать значение по умолчанию для типа данных (например, 0) для ClickHouse null. Обратите внимание, что для NumPy/Pandas по умолчанию значение False в целях повышения производительности. |
column_oriented | bool | False | Возвращать результаты как последовательность колонок, а не строк. Полезно для преобразования данных Python в другие форматы данных, ориентированные на колонки. |
query_tz | str | None | Название часового пояса из базы данных zoneinfo . Этот часовой пояс будет применяться ко всем объектам datetime или Pandas Timestamp, возвращаемым запросом. |
column_tzs | dict | None | Словарь названия колонки на название часового пояса. Как query_tz , но позволяет задавать разные часовые пояса для разных колонок. |
use_extended_dtypes | bool | True | Использовать расширенные типы данных Pandas (например, StringArray) и pandas.NA и pandas.NaT для значений NULL ClickHouse. Применяется только для методов query_df и query_df_stream . |
external_data | ExternalData | None | Объект ExternalData, содержащий файлы или двоичные данные для использования с запросом. См. Расширенные запросы (Внешние данные) |
context | QueryContext | None | Повторно используемый объект QueryContext может использоваться для инкапсуляции вышеуказанных аргументов метода. См. Расширенные запросы (QueryContexts) |
Объект 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
-- Эта версия возвращает DataFrame Pandas вместо QueryResult ClickHouse Connect.query_arrow
-- Эта версия возвращает таблицу PyArrow. Она использует формат ClickHouseArrow
напрямую, поэтому принимает только три аргумента, общие с основным методом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
-- Возвращает данные запроса в виде RecordBlocks PyArrow.
Каждый из этих методов возвращает объект ContextStream
, который необходимо открыть с помощью оператора with
, чтобы начать потребление потока. См. Расширенные запросы (Потоковые запросы) для подробностей и примеров.
Метод insert
клиента
Для общего случая вставки нескольких записей в ClickHouse есть метод Client.insert
. Он принимает следующие параметры:
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
table | str | Обязательный | Таблица ClickHouse для вставки. Разрешено полное имя таблицы (включая базу данных). |
data | Последовательность Последовательностей | Обязательный | Матрица данных для вставки, либо последовательность строк, каждая из которых является последовательностью значений колонок, либо последовательность колонок, каждая из которых является последовательностью значений строк. |
column_names | Последовательность str, или str | '*' | Список имен колонок для матрицы данных. Если используется '*', ClickHouse Connect выполнит "предварительный запрос", чтобы получить все имена колонок для таблицы. |
database | str | '' | Целевая база данных для вставки. Если не указано, будет подразумеваться база данных клиента. |
column_types | Последовательность ClickHouseType | None | Список экземпляров ClickHouseType. Если ни column_types , ни column_type_names не указаны, ClickHouse Connect выполнит "предварительный запрос", чтобы получить все типы колонок для таблицы. |
column_type_names | Последовательность имен типов ClickHouse | None | Список имен типов данных ClickHouse. Если ни column_types , ни column_type_names не указаны, ClickHouse Connect выполнит "предварительный запрос", чтобы получить все типы колонок для таблицы. |
column_oriented | bool | False | Если True, аргумент data считается последовательностью колонок (и "поворот" не будет необходим для вставки данных). В противном случае data интерпретируется как последовательность строк. |
settings | dict | None | См. описание настроек. |
insert_context | InsertContext | None | Можно использовать объект InsertContext, чтобы инкапсулировать аргументы вышеуказанного метода. См. Расширенные вставки (InsertContexts). |
Этот метод возвращает словарь "сводки запроса", как описано в методе "command". Будет сгенерировано исключение, если вставка не удалась по какой-либо причине.
Существуют две специализированные версии основного метода insert
:
insert_df
-- Вместо Python последовательности последовательностей аргументdata
требуетdf
, который должен быть экземпляром DataFrame Pandas. ClickHouse Connect автоматически обрабатывает DataFrame как ресурс с колонной, поэтому параметрcolumn_oriented
не требуется и не доступен.insert_arrow
-- Вместо Python последовательности последовательностей аргументdata
требуетarrow_table
. ClickHouse Connect передает таблицу Arrow без изменений на сервер ClickHouse для обработки, поэтому только аргументыdatabase
иsettings
доступны дополнительно кtable
иarrow_table
.
Примечание: Массив NumPy является действительной последовательностью последовательностей и может использоваться в качестве аргумента data
для основного метода insert
, поэтому специализированный метод не требуется.
Вставки из файлов
clickhouse_connect.driver.tools
включает метод insert_file
, который позволяет вставлять данные непосредственно из файловой системы в существующую таблицу ClickHouse. Парсинг делегируется серверу ClickHouse. insert_file
принимает следующие параметры:
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
client | Client | Обязательный | Клиент driver.Client , используемый для выполнения вставки |
table | str | Обязательный | Таблица ClickHouse, в которую будет выполнена вставка. Полное имя таблицы (включая базу данных) разрешено. |
file_path | str | Обязательный | Путь к файлу данных в корневой файловой системе |
fmt | str | CSV, CSVWithNames | Формат ввода ClickHouse для файла. Если column_names не предоставлены, предполагается, что используется CSVWithNames |
column_names | Последовательность str | None | Список имен колонок в файле данных. Не требуется для форматов, которые включают имена колонок |
database | str | None | База данных таблицы. Игнорируется, если таблица полностью квалифицирована. Если не указана, вставка будет использовать базу данных клиента |
settings | dict | None | См. описание настроек. |
compression | str | None | Признаваемый тип сжатия 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
позволяет использовать HTTP-интерфейс запросов ClickHouse напрямую, используя подключение клиента. Возвращаемое значение является необработанным объектом bytes
. Он предлагает удобную оболочку с привязкой параметров, обработкой ошибок, повторными попытками и управлением настройками с помощью минимального интерфейса:
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
query | str | Обязательный | Любой действительный запрос ClickHouse |
parameters | dict или итератор | None | См. описание параметров. |
settings | dict | None | См. описание настроек. |
fmt | str | None | Формат вывода ClickHouse для возвращаемых байтов. (ClickHouse использует TSV, если не указано) |
use_database | bool | True | Использовать базу данных, назначенную клиенту clickhouse-connect, для контекста запроса |
external_data | ExternalData | None | Объект ExternalData, содержащий файл или двоичные данные для использования с запросом. См. Расширенные запросы (Внешние данные) |
Ответственность за обработку возвращаемого объекта bytes
лежит на вызывающем. Обратите внимание, что Client.query_arrow
является просто тонкой оболочкой вокруг этого метода, использующей формат вывода ClickHouse Arrow
.
Метод raw_stream
клиента
Метод Client.raw_stream
имеет такой же API, как и метод raw_query
, но возвращает объект io.IOBase
, который может быть использован как генератор/источник потока объектов bytes
. В настоящее время он используется методом query_arrow_stream
.
Метод raw_insert
клиента
Метод Client.raw_insert
позволяет напрямую вставлять объекты bytes
или генераторы объектов bytes
, используя подключение клиента. Поскольку он не обрабатывает загрузку вставляемых данных, он имеет высокую производительность. Метод предоставляет опции для указания настроек и формата вставки:
Параметр | Тип | По умолчанию | Описание |
---|---|---|---|
table | str | Обязательный | Либо простое, либо квалифицированное имя таблицы |
column_names | Последовательность[str] | None | Имена колонок для вставочного блока. Требуется, если параметр fmt не включает имена |
insert_block | str, bytes, Генератор[bytes], BinaryIO | Обязательный | Данные для вставки. Строки будут закодированы с использованием кодирования клиента. |
settings | dict | None | См. описание настроек. |
Ответственность за то, чтобы insert_block
был в указанном формате и использовал указанный метод сжатия, лежит на вызывающем. ClickHouse Connect использует эти необработанные вставки для загрузки файлов и таблиц PyArrow, передавая парсинг на сервер ClickHouse.
Утилитные классы и функции
Следующие классы и функции также считаются частью "публичного" API clickhouse-connect
и, как и классы и методы, задокументированные выше, стабильны в рамках минорных обновлений. Изменения, нарушающие совместимость, для этих классов и функций произойдут только с минорным (а не патчевым) релизом и будут доступны со статусом устаревания в течение как минимум одного минорного релиза.
Исключения
Все пользовательские исключения (включая те, которые определены в спецификации DB API 2.0) определены в модуле clickhouse_connect.driver.exceptions
.
Исключения, которые фактически обнаруживает драйвер, будут использовать один из этих типов.
Утилиты Clickhouse SQL
Функции и класс DT64Param в модуле clickhouse_connect.driver.binding
могут использоваться для корректной постройки и экранирования запросов SQL ClickHouse. Аналогично, функции в модуле clickhouse_connect.driver.parser
могут использоваться для парсинга имен типов данных ClickHouse.
Многопоточные, многопроцессорные и асинхронные/событийно-ориентированные случаи использования
ClickHouse Connect хорошо работает в многопоточных, многопроцессорных и асинхронных приложениях с управлением событийными циклами. Все обработка запросов и вставок происходит в одном потоке, поэтому операции, как правило, являются безопасными для потоков. (Параллельная обработка некоторых операций на низком уровне является возможным будущим улучшением, чтобы преодолеть производственные потери от одного потока, но даже в этом случае безопасность потоков будет поддерживаться).
Поскольку каждый запрос или вставка выполняется с сохранением состояния в своем собственном объекте QueryContext или InsertContext, соответственно, эти вспомогательные объекты не являются безопасными для потоков и не должны использоваться между несколькими потоками обработки. См. дополнительное обсуждение объектов контекста в следующих разделах.
Кроме того, в приложении, где одновременно выполняется два или более запросов и/или вставок, есть два дополнительных момента, которые следует учитывать. Первый - это "сессия" ClickHouse, связанная с запросом/вставкой, а второй - это пул соединений HTTP, используемый экземплярами клиента ClickHouse Connect.
Обертка Asyncclient
С версии 0.7.16 ClickHouse Connect предоставляет асинхронную обертку над обычным Client
,
так что клиент можно использовать в среде asyncio
.
Для получения экземпляра AsyncClient
вы можете использовать фабричную функцию get_async_client
,
которая принимает те же параметры, что и стандартный get_client
:
AsyncClient
имеет те же методы с теми же параметрами, что и стандартный Client
, но они являются сопрограммами, когда это применимо. Внутренние методы класса Client
, которые выполняют операции ввода-вывода, обернуты в вызов run_in_executor.
Производительность при многопоточном выполнении улучшится при использовании обертки AsyncClient
,
так как потоки выполнения и GIL будут освобождены во время ожидания завершения операций ввода-вывода.
Примечание: в отличие от обычного Client
, AsyncClient
по умолчанию устанавливает autogenerate_session_id
в значение False
.
См. также: пример run_async.
Управление идентификаторами сессий ClickHouse
Каждый запрос ClickHouse выполняется в контексте "сессии" ClickHouse. Сессии в настоящее время используются для двух целей:
- Чтобы ассоциировать конкретные настройки ClickHouse с несколькими запросами (см. настройки пользователя). Команда ClickHouse
SET
используется для изменения настроек в рамках пользовательской сессии. - Для отслеживания временных таблиц.
По умолчанию каждый запрос, выполняемый с экземпляром клиента ClickHouse Connect, использует один и тот же идентификатор сессии, чтобы обеспечить эту функциональность сессии. То есть команды SET
и работа с временными таблицами будут выполняться как ожидалось при использовании одного клиента ClickHouse. Однако по замыслу сервер ClickHouse не позволяет выполнять параллельные запросы внутри одной сессии. В результате существует два варианта для приложения ClickHouse Connect, которое будет выполнять параллельные запросы.
- Создавать отдельный экземпляр
Client
для каждого потока выполнения (потока, процесса или обработчика событий), который будет иметь свой собственный идентификатор сессии. Это, как правило, лучший подход, так как он сохраняет состояние сессии для каждого клиента. - Использовать уникальный идентификатор сессии для каждого запроса. Это позволяет избежать проблемы параллельной сессии в тех случаях, когда временные таблицы или общие настройки сессии не требуются. (Общие настройки также могут быть предоставлены при создании клиента, но они отправляются с каждым запросом и не связаны с сессией). Уникальный идентификатор сессии может быть добавлен в словарь
settings
для каждого запроса, или вы можете отключить общую настройкуautogenerate_session_id
:
В этом случае ClickHouse Connect не отправит никаких идентификаторов сессий, и сервер ClickHouse сгенерирует случайный идентификатор сессии. ВAgain, временные таблицы и настройки уровня сессий не будут доступны.
Настройка пула 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
.
Потоковые запросы
Блоки данных
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 буфер данных для медленной обработки
Из-за ограничений в HTTP-протоколе, если блоки обрабатываются значительно медленнее, чем сервер ClickHouse передает
данные, сервер ClickHouse закроет соединение, что приведет к выбросу исключения в потоке обработки. Часть этого можно смягчить, увеличив размер буфера HTTP-потока (по умолчанию 10 мегабайт) с использованием общей настройки http_buffer_size
. Большие значения http_buffer_size
должны быть допустимыми в этой ситуации, если в приложении достаточно памяти.
Данные в буфере хранятся в сжатом виде, если используется сжатие lz4
или zstd
, поэтому использование этих типов сжатия увеличит общий доступный буфер.
StreamContexts
Каждый из методов query_*_stream
(например, query_row_block_stream
) возвращает объект ClickHouse StreamContext
, который является комбинированным контекстом/generator Python. Это базовое использование:
Обратите внимание, что попытка использовать StreamContext без оператора with
вызовет ошибку. Использование контекста Python гарантирует, что поток (в данном случае, поток HTTP-ответа) будет корректно закрыт, даже если не все данные будут потреблены и/или во время обработки возникла ошибка. Также StreamContexts могут использоваться только один раз для потребления потока. Попытка использовать StreamContext после того, как он был закрыт, приведёт к возникновению StreamClosedError
.
Вы можете использовать свойство source
StreamContext для доступа к родительскому объекту QueryResult
, который включает имена и типы колонок.
Типы потоков
Метод 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
возвращает результат, отформатированный в ArrowStream
ClickHouse, как pyarrow.ipc.RecordBatchStreamReader
, обернутый в StreamContext. Каждая итерация потока возвращает RecordBlock PyArrow.
Форматы чтения
Форматы чтения контролируют типы данных значений, возвращаемых из клиентских методов query
, query_np
и query_df
. (Методы raw_query
и query_arrow
не изменяют входящие данные из ClickHouse, поэтому контроль формата не применяется.) Например, если формат чтения для UUID изменяется с формата по умолчанию native
на альтернативный формат string
, запрос ClickHouse к колонке UUID
будет возвращен как строковые значения (используя стандартный формат 8-4-4-4-12 RFC 1422), а не как объекты UUID Python.
Аргумент "тип данных" для любой функции форматирования может включать подстановочные знаки. Формат представляет собой одну строку в нижнем регистре.
Форматы чтения могут быть установлены на нескольких уровнях:
- Глобально, с использованием методов, определенных в пакете
clickhouse_connect.datatypes.format
. Это будет управлять форматом конфигурированного типа данных для всех запросов.
- Для целого запроса, используя необязательный аргумент словаря
query_formats
. В этом случае любая колонка (или подколонка) заданного типа данных будет использовать заданный формат.
- Для значений в конкретной колонке, используя необязательный аргумент словаря
column_formats
. Ключом является имя колонки, возвращаемой ClickHouse, и формат для колонки данных или вторичный словарь "формата" с именем типа ClickHouse и значением формата запроса. Этот вторичный словарь может использоваться для вложенных типов колонн, таких как кортежи или карты.
Опции формата чтения (типы Python)
ClickHouse Type | Native Python Type | Read Formats | Comments |
---|---|---|---|
Int[8-64], UInt[8-32] | int | - | |
UInt64 | int | signed | Superset в настоящее время не обрабатывает большие беззнаковые значения UInt64 |
[U]Int[128,256] | int | string | Значения int в Pandas и NumPy достигают 64 бит, поэтому эти значения могут возвращаться в виде строк |
Float32 | float | - | Все Python float имеют внутренний формат 64 бита |
Float64 | float | - | |
Decimal | decimal.Decimal | - | |
String | string | bytes | Столбцы ClickHouse типа String не имеют встроенного кодирования, поэтому их также используют для бинарных данных переменной длины |
FixedString | bytes | string | FixedStrings представляют собой массивы байтов фиксированной длины, но иногда их обрабатывают как строки в Python |
Enum[8,16] | string | string, int | Python enum не принимает пустые строки, поэтому все enum отображаются как строки или как их базовое целочисленное значение. |
Date | datetime.date | int | ClickHouse хранит даты как дни с 01/01/1970. Это значение доступно как int |
Date32 | datetime.date | int | То же самое, что и для Date, но с более широким диапазоном дат |
DateTime | datetime.datetime | int | ClickHouse хранит DateTime в эпохе в секундах. Это значение доступно как int |
DateTime64 | datetime.datetime | int | Python datetime.datetime ограничен точностью до микросекунд. Сырой 64-битный int доступен |
IPv4 | ipaddress.IPv4Address | string | IP-адреса можно читать как строки, и корректно отформатированные строки могут быть вставлены как IP-адреса |
IPv6 | ipaddress.IPv6Address | string | IP-адреса можно читать как строки и корректно отформатированные могут быть вставлены как IP-адреса |
Tuple | dict or tuple | tuple, json | Именованные кортежи по умолчанию возвращаются как словари. Именованные кортежи также могут быть возвращены как JSON-строки |
Map | dict | - | |
Nested | Sequence[dict] | - | |
UUID | uuid.UUID | string | UUID можно читать как строки, отформатированные в соответствии с RFC 4122 |
JSON | dict | string | По умолчанию возвращается словарь Python. Формат string вернет строку JSON |
Variant | object | - | Возвращает соответствующий тип Python для хранимого ClickHouse типа данных |
Dynamic | object | - | Возвращает соответствующий тип Python для хранимого ClickHouse типа данных |
Внешние данные
Запросы 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
.
Часовые пояса
Существует несколько механизмов для применения часового пояса к значениям DateTime и DateTime64 в ClickHouse. Внутренне сервер ClickHouse всегда хранит любой объект DateTime или DateTime64 как число, не зависящее от часового пояса, представляющее секунды с эпохи, 1970-01-01 00:00:00 UTC. Для значений DateTime64 такое представление может быть в миллисекундах, микросекундах или наносекундах с момента эпохи, в зависимости от точности. В результате применение любой информации о часовом поясе всегда происходит на стороне клиента. Обратите внимание, что это включает в себя значительные дополнительные вычисления, поэтому в приложениях, критичных к производительности, рекомендуется рассматривать типы DateTime как отметки времени эпохи, за исключением отображения для пользователя и преобразования (например, метки времени Pandas всегда являются 64-битным целым числом, представляющим эпоху в наносекундах для повышения производительности).
При использовании типов данных, учитывающих часовой пояс, в запросах - в частности, объекта datetime.datetime
в Python -- clickhouse-connect
применяет часовой пояс на стороне клиента, используя следующие правила приоритета:
- Если для метода запроса указан параметр
client_tzs
, применяется конкретный часовой пояс колонки - Если колонка ClickHouse имеет метаданные о часовом поясе (т.е. это тип, такой как DateTime64(3, 'America/Denver')), применяется часовой пояс колонки ClickHouse. (Обратите внимание, что эти метаданные о часовом поясе недоступны для
clickhouse-connect
для колонок DateTime до версии ClickHouse 23.2) - Если для метода запроса указан параметр
query_tz
, применяется "часовой пояс запроса". - Если настройка часового пояса применяется к запросу или сессии, применяется этот часовой пояс. (Эта функциональность еще не выпущена в сервере ClickHouse)
- Наконец, если параметр клиента
apply_server_timezone
установлен в True (по умолчанию), применяется часовой пояс сервера ClickHouse.
Обратите внимание, что если примененный часовой пояс на основе этих правил - это UTC, clickhouse-connect
всегда вернет объект Python datetime.datetime
, не зависящий от часового пояса. Дополнительная информация о часовом поясе может быть добавлена к этому объекту, не зависящему от часового пояса, кодом приложения, если это необходимо.
Вставка данных с ClickHouse Connect: Расширенное использование
InsertContexts
ClickHouse Connect выполняет все вставки в рамках InsertContext. InsertContext включает все значения, отправленные в качестве аргументов методу клиента insert
. Кроме того, когда InsertContext первоначально создается, ClickHouse Connect извлекает типы данных для столбцов вставки, необходимые для эффективных вставок в формате Native. Повторное использование InsertContext для нескольких вставок позволяет избежать этого "предварительного запроса", и вставки выполняются быстрее и эффективнее.
InsertContext можно получить с помощью метода клиента create_insert_context
. Метод принимает те же аргументы, что и функция insert
. Обратите внимание, что только свойство data
InsertContexts должно изменяться для повторного использования. Это согласуется с его предполагаемым назначением предоставления повторно используемого объекта для многократных вставок новых данных в одну и ту же таблицу.
InsertContexts включают изменяемое состояние, которое обновляется в процессе вставки, поэтому они не являются безопасными для потоков.
Форматы записи
Форматы записи в настоящее время реализованы для ограниченного числа типов. В большинстве случаев ClickHouse Connect будет пытаться автоматически определить правильный формат записи для столбца, проверяя тип первого (не нулевого) значения данных. Например, если вставляется значение в столбец DateTime и первое значение вставки в столбец - целое число Python, ClickHouse Connect будет напрямую вставлять целочисленное значение, предполагая, что это значение действительно представляет секунду эпохи.
В большинстве случаев нет необходимости переопределять формат записи для типа данных, но соответствующие методы в пакете clickhouse_connect.datatypes.format
могут быть использованы для этого на глобальном уровне.
Опции формата записи
ClickHouse Type | Native Python Type | Write Formats | Comments |
---|---|---|---|
Int[8-64], UInt[8-32] | int | - | |
UInt64 | int | ||
[U]Int[128,256] | int | ||
Float32 | float | ||
Float64 | float | ||
Decimal | decimal.Decimal | ||
String | string | ||
FixedString | bytes | string | Если вставить как строку, дополнительные байты будут установлены в ноль |
Enum[8,16] | string | ||
Date | datetime.date | int | ClickHouse хранит даты как дни с 01/01/1970. Для типов int будет предполагаться, что это значение "даты эпохи" |
Date32 | datetime.date | int | То же самое, что и для Date, но для более широкого диапазона дат |
DateTime | datetime.datetime | int | ClickHouse хранит DateTime в эпохе в секундах. Для типов int будет предполагаться, что это значение "секунды эпохи" |
DateTime64 | datetime.datetime | int | Python datetime.datetime ограничен точностью до микросекунд. Сырой 64-битный int доступен |
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 |
Дополнительные опции
ClickHouse Connect предоставляет ряд дополнительных опций для продвинутых случаев использования.
Глобальные настройки
Существует небольшое количество настроек, которые глобально контролируют поведение 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 Map. json следует использовать для вставок в JSON столбцы, map для колонок ClickHouse Map |
product_name | Строка, которая передается вместе с запросом в ClickHouse для отслеживания приложения, использующего ClickHouse Connect. Должна быть в формате <product_name>/<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 | Использовать версию клиентского протокола. Это необходимо для колонок временных меток с учетом часовых поясов, но нарушает работу с текущей версией chproxy |
max_error_size | 1024 | Максимальное количество символов, которые будут возвращены в сообщений об ошибках клиента. Установите 0 для этой настройки, чтобы получить полное сообщение об ошибке ClickHouse. По умолчанию 1024 символа. | |
send_os_user | True | True, False | Включить обнаруживаемое имя пользователя операционной системы в информацию клиента, отправленную в ClickHouse (HTTP User-Agent строка) |
http_buffer_size | 10MB | Размер (в байтах) "внутреннего" буфера, используемого для потоковых запросов HTTP |
Сжатие
ClickHouse Connect поддерживает сжатие lz4, zstd, brotli и gzip как для результатов запросов, так и для вставок. Всегда имейте в виду, что использование сжатия обычно связано с компромиссом между пропускной способностью сети / скоростью передачи и использованием CPU (как на стороне клиента, так и на стороне сервера).
Чтобы получать сжатые данные, параметр сервера ClickHouse enable_http_compression
должен быть установлен в 1, или у пользователя должен быть разрешение на изменение настройки на основе "каждого запроса".
Сжатие контролируется параметром compress
при вызове фабричного метода clickhouse_connect.get_client
. По умолчанию compress
установлен в True
, что вызовет использование настроек сжатия по умолчанию. Для запросов, выполненных с использованием методов клиента query
, query_np
и query_df
, ClickHouse Connect добавит заголовок Accept-Encoding
с кодировками lz4
, zstd
, br
(brotli, если библиотека brotli установлена), gzip
и deflate
к запросам, выполненным с использованием метода клиента query
(и косвенно для query_np
и query_df
). (Для большинства запросов сервер ClickHouse будет возвращать данные сжатые с помощью zstd
.) Для вставок по умолчанию ClickHouse Connect будет сжимать блоки вставок с помощью сжатия lz4
и отправлять HTTP заголовок Content-Encoding: lz4
.
Параметр compress
в методе get_client
также может быть установлен на конкретный метод сжатия, один из lz4
, zstd
, br
или gzip
. Этот метод будет использоваться как для вставок, так и для результатов запросов (если это поддерживается сервером ClickHouse). Необходимые библиотеки сжатия zstd
и lz4
теперь устанавливаются по умолчанию с ClickHouse Connect. Если указан br
/brotli, библиотека brotli должна быть установлена отдельно.
Обратите внимание, что методы клиента raw*
не используют сжатие, указанное клиентской конфигурацией.
Мы также не рекомендуем использовать сжатие gzip
, поскольку оно значительно медленнее, чем альтернативы как для сжатия, так и для разжатия данных.
Поддержка HTTP-прокси
ClickHouse Connect добавляет базовую поддержку HTTP-прокси с использованием библиотеки urllib3
. Она распознает стандартные переменные среды HTTP_PROXY
и HTTPS_PROXY
. Обратите внимание, что использование этих переменных среды будет применяться ко всем клиентам, созданным с помощью метода clickhouse_connect.get_client
. В качестве альтернативы, для конфигурации для каждого клиента вы можете использовать параметры http_proxy
или https_proxy
метода get_client. Для получения подробностей об реализации поддержки HTTP-прокси смотрите документацию urllib3.
Для использования прокси Socks вы можете отправить urllib3
SOCKSProxyManager в качестве аргумента pool_mgr
в get_client
. Обратите внимание, что это потребует установки библиотеки PySocks либо напрямую, либо с использованием опции [socks]
для зависимости urllib3
.
Устаревший тип данных JSON
Экспериментальный тип данных Object
(или Object('json')
) устарел и должен избегаться в производственной среде. ClickHouse Connect продолжает предоставлять ограниченную поддержку данного типа данных для обратной совместимости. Обратите внимание, что эта поддержка не включает запросы, которые должны возвращать "узловые" или "родительские" значения JSON в виде словарей или эквивалентно, и такие запросы приведут к исключению.
"Новые" типы данных Variant/Dynamic/JSON (экспериментальная функция)
Начиная с версии 0.8.0, clickhouse-connect
предоставляет экспериментальную поддержку новых (также экспериментальных) типов ClickHouse: Variant, Dynamic и JSON.
Примечания по использованию
- Данные JSON могут вставляться как словарь Python или как строка JSON, содержащая JSON-объект
{}
. Другие формы данных JSON не поддерживаются. - Запросы, использующие подколонки/пути для этих типов, вернут тип подколонки.
- См. основную документацию ClickHouse для других примечаний по использованию.
Известные ограничения
- Каждый из этих типов должен быть включен в настройках ClickHouse перед использованием.
- Новый тип JSON доступен начиная с версии ClickHouse 24.8.
- Из-за изменений внутреннего формата
clickhouse-connect
совместим только с типами Variant, начиная с версии ClickHouse 24.7. - Возвращаемые JSON-объекты будут возвращать только количество элементов, равное
max_dynamic_paths
(по умолчанию 1024). Это будет исправлено в будущих релизах. - Вставки в столбцы
Dynamic
всегда будут строковым представлением значения Python. Это будет исправлено в будущих релизах, как только https://github.com/ClickHouse/ClickHouse/issues/70395 будет исправлено. - Реализация новых типов еще не была оптимизирована в C-коде, поэтому производительность может быть несколько ниже, чем у более простых, установленных типов данных.