API драйвера ClickHouse Connect

Примечание

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

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

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

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

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

Parameter	Type	Default	Description
interface	str	http	Должно быть http или https.
host	str	localhost	Имя хоста или IP-адрес сервера ClickHouse. Если не задан, используется `localhost`.
port	int	8123 or 8443	HTTP- или HTTPS-порт ClickHouse. Если не задан, по умолчанию используется 8123, или 8443, если secure = True или interface = https.
username	str	default	Имя пользователя ClickHouse. Если не задано, будет использован пользователь ClickHouse `default`.
password	str	<empty string>	Пароль для 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 or str	True	Включить сжатие для HTTP-вставок и результатов запросов ClickHouse. См. Additional Options (Compression).
query_limit	int	0 (unlimited)	Максимальное количество строк, возвращаемых для любого ответа `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 system.query_log.
pool_mgr	obj	<default PoolManager>	Объект PoolManager из библиотеки `urllib3`, который будет использоваться. Для продвинутых сценариев, требующих нескольких пулов соединений к разным хостам.
http_proxy	str	None	Адрес HTTP-прокси (эквивалентно установке переменной окружения HTTP_PROXY).
https_proxy	str	None	Адрес HTTPS-прокси (эквивалентно установке переменной окружения HTTPS_PROXY).
apply_server_timezone	bool	True	Использовать временную зону сервера для результатов запросов с учётом часовых поясов. См. Timezone Precedence.
show_clickhouse_errors	bool	True	Включать подробные сообщения об ошибках сервера ClickHouse и коды исключений в исключения клиента.
autogenerate_session_id	bool	None	Переопределить глобальную настройку `autogenerate_session_id`. Если True, автоматически генерировать идентификатор сессии UUID4, когда он не предоставлен.
proxy_path	str	<empty string>	Необязательный префикс пути, добавляемый к URL сервера ClickHouse для конфигураций с прокси.
form_encode_query_params	bool	False	Отправлять параметры запроса как form-encoded данные в теле запроса вместо параметров в URL. Полезно для запросов с большим числом параметров, которые могут превысить ограничения длины URL.
rename_response_column	str	None	Необязательная callback-функция или отображение имён столбцов для переименования столбцов ответа в результатах запросов.

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

Parameter	Type	Default	Description
verify	bool	True	Проверяет сертификат TLS/SSL сервера ClickHouse (имя хоста, срок действия и т. д.) при использовании HTTPS/TLS.
ca_cert	str	None	Если verify=True, путь к файлу корневого удостоверяющего центра (Certificate Authority) для проверки сертификата сервера 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

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

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

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

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

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

import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)
# Результат: '22.10.1.98' \{#output-2210198}

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

import clickhouse_connect

client = clickhouse_connect.get_client(host='play.clickhouse.com', secure=True, port=443, user='play', password='clickhouse')
print(client.command('SELECT timezone()'))
# Результат: 'Etc/UTC' \{#output-etcutc}

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

import clickhouse_connect

client = clickhouse_connect.get_client(
    host='play.clickhouse.com',
    user='play',
    password='clickhouse',
    port=443,
    session_id='example_session_1',
    connect_timeout=15,
    database='github',
    settings={'distributed_ddl_task_timeout':300},
)
print(client.database)
# Результат: 'github' \{#output-github}

Жизненный цикл клиента и рекомендации по использованию

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

Основные принципы

Повторно используйте клиентов: Создавайте клиентов один раз при запуске приложения и используйте их повторно на протяжении всего времени его работы
Избегайте частого создания: Не создавайте нового клиента для каждого запроса или вызова (это тратит сотни миллисекунд на каждую операцию)
Корректно освобождайте ресурсы: Всегда закрывайте клиентов при завершении работы, чтобы освободить ресурсы пула подключений
Используйте совместно, когда это возможно: Один клиент может обрабатывать множество параллельных запросов через свой пул подключений (см. примечания по работе с потоками ниже)

Базовые шаблоны

✅ Хорошо: переиспользовать один и тот же клиент

import clickhouse_connect

# Создается один раз при запуске \{#create-once-at-startup}
client = clickhouse_connect.get_client(host='my-host', username='default', password='password')

# Используется повторно для всех запросов \{#reuse-for-all-queries}
for i in range(1000):
    result = client.query('SELECT count() FROM users')

# Закрывается при завершении работы \{#close-on-shutdown}
client.close()

❌ Плохо: каждый раз заново создавать клиентов

# ПЛОХО: Создает 1000 клиентов с дорогостоящими накладными расходами на инициализацию \{#bad-creates-1000-clients-with-expensive-initialization-overhead}
for i in range(1000):
    client = clickhouse_connect.get_client(host='my-host', username='default', password='password')
    result = client.query('SELECT count() FROM users')
    client.close()

Многопоточные приложения

Примечание

Экземпляры клиента НЕ являются потокобезопасными при использовании идентификаторов сеансов. По умолчанию у клиентов автоматически генерируется идентификатор сеанса, и параллельные запросы в одном и том же сеансе приведут к возникновению ProgrammingError.

Чтобы безопасно совместно использовать экземпляр клиента между потоками:

import clickhouse_connect
import threading

# Вариант 1: Отключение сессий (рекомендуется для разделяемых клиентов) \{#option-1-disable-sessions-recommended-for-shared-clients}
client = clickhouse_connect.get_client(
    host='my-host',
    username='default',
    password='password',
    autogenerate_session_id=False  # Необходимо для потокобезопасности
)

def worker(thread_id):
    # Теперь все потоки могут безопасно использовать один клиент
    result = client.query(f"SELECT {thread_id}")
    print(f"Thread {thread_id}: {result.result_rows[0][0]}")


threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

client.close()
# Вывод: \{#output}
# Поток 0: 0 \{#thread-0-0}
# Поток 7: 7 \{#thread-7-7}
# Поток 1: 1 \{#thread-1-1}
# Поток 9: 9 \{#thread-9-9}
# Поток 4: 4 \{#thread-4-4}
# Поток 2: 2 \{#thread-2-2}
# Поток 8: 8 \{#thread-8-8}
# Поток 5: 5 \{#thread-5-5}
# Поток 6: 6 \{#thread-6-6}
# Поток 3: 3 \{#thread-3-3}

Альтернативный подход к сессиям: Если вам нужны сессии (например, для временных таблиц), создавайте отдельный клиент для каждого потока:

def worker(thread_id):
    # Каждый поток получает собственный клиент с изолированной сессией
    client = clickhouse_connect.get_client(host='my-host', username='default', password='password')
    client.command('CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory')
    # ... использовать временную таблицу ...
    client.close()

Корректная очистка

Всегда закрывайте клиентов при завершении работы. Обратите внимание, что client.close() освобождает ресурсы клиента и закрывает HTTP‑соединения из пула только в том случае, если клиент владеет собственным пулом (например, когда он создан с пользовательскими параметрами TLS/прокси). Для стандартного общего пула используйте client.close_connections() для явной очистки сокетов; в противном случае соединения автоматически освобождаются по истечении времени простоя и при завершении процесса.

client = clickhouse_connect.get_client(host='my-host', username='default', password='password')
try:
    result = client.query('SELECT 1')
finally:
    client.close()

Или используйте контекстный менеджер:

with clickhouse_connect.get_client(host='my-host', username='default', password='password') as client:
    result = client.query('SELECT 1')

Когда использовать несколько клиентов

Несколько клиентов уместны в следующих случаях:

Разные серверы: Один клиент для каждого сервера или кластера ClickHouse
Разные учетные данные: Отдельные клиенты для разных пользователей или уровней доступа
Разные базы данных: Когда нужно работать с несколькими базами данных
Изолированные сессии: Когда требуются отдельные сессии для временных таблиц или настроек, зависящих от сессии
Изоляция по потокам: Когда потокам нужны независимые сессии (как показано выше)

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

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

Аргумент parameters

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

Привязка на стороне сервера

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

Привязка на стороне сервера с использованием словаря Python, значением DateTime и строковым значением

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {'table': 'my_table', 'v1': my_date, 'v2': "a string with a single quote'"}
client.query('SELECT * FROM {table:Identifier} WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}', parameters=parameters)

Это приводит к выполнению следующего запроса на сервере:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

Примечание

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

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

ClickHouse Connect также поддерживает привязку параметров на стороне клиента, что даёт большую гибкость при генерации шаблонных SQL‑запросов. Для привязки на стороне клиента аргумент parameters должен быть словарём или последовательностью. Привязка на стороне клиента использует форматирование строк в стиле «printf» в Python для подстановки параметров.

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

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

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {'v1': my_date, 'v2': "a string with a single quote'"}
client.query('SELECT * FROM my_table WHERE date >= %(v1)s AND string ILIKE %(v2)s', parameters=parameters)

При этом на сервере выполняется следующий запрос:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

Пример с типами Python Sequence (tuple), Float64 и IPv4Address

import ipaddress

parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query('SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s', parameters=parameters)

В результате на сервере выполняется следующий запрос:

SELECT *
FROM some_table
WHERE metric >= 35200.44
  AND ip_address = '68.61.4.254''

Примечание

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

Оберните значение Python datetime.datetime в экземпляр нового класса DT64Param, например:

  query = 'SELECT {p1:DateTime64(3)}'  # Привязка на стороне сервера с помощью словаря
  parameters={'p1': DT64Param(dt_value)}

  query = 'SELECT %s as string, toDateTime64(%s,6) as dateTime' # Привязка на стороне клиента с помощью списка 
  parameters=['a string', DT64Param(datetime.now())]

Если используется словарь значений параметров, добавьте суффикс _64 к имени параметра

  query = 'SELECT {p1:DateTime64(3)}, {a1:Array(DateTime(3))}'  # Привязка на стороне сервера с помощью словаря

  parameters={'p1_64': dt_value, 'a1_64': [dt_value1, dt_value2]}

Аргумент settings

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

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

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

settings = {'merge_tree_min_rows_for_concurrent_read': 65535,
            'session_id': 'session_1234',
            'use_skip_indexes': False}
client.query("SELECT event_type, sum(timeout) FROM event_errors WHERE event_time > '2022-08-01'", settings=settings)

Метод клиента `command`

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

Parameter	Type	Default	Description
cmd	str	Required	SQL-выражение ClickHouse, которое возвращает одно значение или одну строку значений.
parameters	dict or iterable	None	См. описание аргумента `parameters`.
data	str or bytes	None	Необязательные данные, включаемые в команду как тело POST-запроса.
settings	dict	None	См. описание аргумента `settings`.
use_database	bool	True	Использовать базу данных клиента (указывается при создании клиента). False означает, что команда будет использовать базу данных сервера ClickHouse по умолчанию для подключенного пользователя.
external_data	ExternalData	None	Объект `ExternalData`, содержащий файловые или двоичные данные для использования в запросе. См. Advanced Queries (External Data)

Примеры команд

Операторы DDL

import clickhouse_connect

client = clickhouse_connect.get_client()

# Создание таблицы \{#create-a-table}
result = client.command("CREATE TABLE test_command (col_1 String, col_2 DateTime) ENGINE MergeTree ORDER BY tuple()")
print(result)  # Возвращает QuerySummary с query_id

# Отображение определения таблицы \{#show-table-definition}
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Вывод: \{#output}
# CREATE TABLE default.test_command \{#create-table-defaulttest_command}
# (
#     `col_1` String, \{#col_1-string}
#     `col_2` DateTime \{#col_2-datetime}
# )
# ENGINE = MergeTree \{#engine-mergetree}
# ORDER BY tuple() \{#order-by-tuple}
# SETTINGS index_granularity = 8192 \{#settings-index_granularity-8192}

# Удаление таблицы \{#drop-table}
client.command("DROP TABLE test_command")

Простые запросы, возвращающие одно значение

import clickhouse_connect

client = clickhouse_connect.get_client()

# Результат с одним значением \{#single-value-result}
count = client.command("SELECT count() FROM system.tables")
print(count)
# Вывод: 151 \{#output-151}

# Версия сервера \{#server-version}
version = client.command("SELECT version()")
print(version)
# Вывод: "25.8.2.29" \{#output-258229}

Команды с параметрами

import clickhouse_connect

client = clickhouse_connect.get_client()

# Использование параметров на стороне клиента \{#using-client-side-parameters}
table_name = "system"
result = client.command(
    "SELECT count() FROM system.tables WHERE database = %(db)s",
    parameters={"db": table_name}
)

# Использование параметров на стороне сервера \{#using-server-side-parameters}
result = client.command(
    "SELECT count() FROM system.tables WHERE database = {db:String}",
    parameters={"db": "system"}
)

Команды с настройками

import clickhouse_connect

client = clickhouse_connect.get_client()

# Выполнить команду с конкретными настройками \{#execute-command-with-specific-settings}
result = client.command(
    "OPTIMIZE TABLE large_table FINAL",
    settings={"optimize_throw_if_noop": 1}
)

Метод клиента `query`

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

Parameter	Type	Default	Description
query	str	Required	SQL-запрос ClickHouse SELECT или DESCRIBE.
parameters	dict or iterable	None	См. описание `parameters`.
settings	dict	None	См. описание `settings`.
query_formats	dict	None	Спецификация форматирования типов данных для значений результата. См. Advanced Usage (Read Formats).
column_formats	dict	None	Форматирование типов данных по столбцам. См. Advanced Usage (Read Formats).
encoding	str	None	Кодировка, используемая для преобразования столбцов ClickHouse типа String в строки Python. По умолчанию Python использует `UTF-8`, если она явно не задана.
use_none	bool	True	Использовать тип Python None для значений ClickHouse `NULL`. Если False, использовать значение по умолчанию для типа данных (например, 0) для значений `NULL` в ClickHouse. Примечание: по умолчанию значение False используется для NumPy/Pandas по соображениям производительности.
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` для значений ClickHouse `NULL`. Применяется только к методам `query_df` и `query_df_stream`.
external_data	ExternalData	None	Объект ExternalData, содержащий файловые или бинарные данные для использования в запросе. См. Advanced Queries (External Data).
context	QueryContext	None	Повторно используемый объект QueryContext, который может быть использован для инкапсуляции вышеперечисленных аргументов метода. См. Advanced Queries (QueryContexts).

Примеры запросов

Простой запрос

import clickhouse_connect

client = clickhouse_connect.get_client()

# Простой SELECT-запрос \{#simple-select-query}
result = client.query("SELECT name, database FROM system.tables LIMIT 3")

# Получение результатов в виде строк \{#access-results-as-rows}
for row in result.result_rows:
    print(row)
# Вывод: \{#output}
# ('CHARACTER_SETS', 'INFORMATION_SCHEMA') \{#character_sets-information_schema}
# ('COLLATIONS', 'INFORMATION_SCHEMA') \{#collations-information_schema}
# ('COLUMNS', 'INFORMATION_SCHEMA') \{#columns-information_schema}

# Получение имен и типов столбцов \{#access-column-names-and-types}
print(result.column_names)
# Вывод: ("name", "database") \{#output-name-database}
print([col_type.name for col_type in result.column_types])
# Вывод: ['String', 'String'] \{#output-string-string}

Доступ к результатам запроса

import clickhouse_connect

client = clickhouse_connect.get_client()

result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

# Построчный доступ (по умолчанию) \{#row-oriented-access-default}
print(result.result_rows)
# Вывод: [[0, "0"], [1, "1"], [2, "2"]] \{#output-0-0-1-1-2-2}

# Постолбцовый доступ \{#column-oriented-access}
print(result.result_columns)
# Вывод: [[0, 1, 2], ["0", "1", "2"]] \{#output-0-1-2-0-1-2}

# Именованные результаты (список словарей) \{#named-results-list-of-dictionaries}
for row_dict in result.named_results():
    print(row_dict)
# Вывод:  \{#output}
# {"number": 0, "str": "0"} \{#number-0-str-0}
# {"number": 1, "str": "1"} \{#number-1-str-1}
# {"number": 2, "str": "2"} \{#number-2-str-2}

# Первая строка как словарь \{#first-row-as-dictionary}
print(result.first_item)
# Вывод: {"number": 0, "str": "0"} \{#output-number-0-str-0}

# Первая строка как кортеж \{#first-row-as-tuple}
print(result.first_row)
# Вывод: (0, "0") \{#output-0-0}

Запрос с клиентскими параметрами

import clickhouse_connect

client = clickhouse_connect.get_client()

# Использование параметров-словаря (в стиле printf) \{#using-dictionary-parameters-printf-style}
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)

# Использование параметров-кортежа \{#using-tuple-parameters}
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)

Запрос с серверными параметрами

import clickhouse_connect

client = clickhouse_connect.get_client()

# Привязка на стороне сервера (более безопасна, обеспечивает лучшую производительность для SELECT-запросов) \{#server-side-binding-more-secure-better-performance-for-select-queries}
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)

Запрос с параметрами

import clickhouse_connect

client = clickhouse_connect.get_client()

# Передать настройки ClickHouse вместе с запросом \{#pass-clickhouse-settings-with-the-query}
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)

Объект `QueryResult`

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

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

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

Подробная информация о потоковой выдаче результатов запросов (с использованием объектов StreamContext) приведена в разделе Advanced Queries (Streaming Queries).

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

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

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

Для потоковой выборки больших наборов результатов ClickHouse Connect предоставляет несколько методов потоковой передачи. Подробности и примеры см. в разделе Advanced Queries (Streaming Queries).

Метод клиента `insert`

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

Параметр	Тип	Значение по умолчанию	Описание
table	str	Required	Таблица ClickHouse, в которую выполняется вставка. Допускается полное имя таблицы (включая базу данных).
data	Sequence of Sequences	Required	Матрица данных для вставки — либо последовательность строк, каждая из которых является последовательностью значений столбцов, либо последовательность столбцов, каждый из которых является последовательностью значений строк.
column_names	Sequence of str, or str	'*'	Список `column_names` для матрицы данных. Если вместо него используется `*`, ClickHouse Connect выполнит «предзапрос» для получения всех имён столбцов таблицы.
database	str	''	Целевая база данных для вставки. Если не указано, будет использована база данных, настроенная для клиента.
column_types	Sequence of ClickHouseType	None	Список экземпляров `ClickHouseType`. Если не указаны ни `column_types`, ни `column_type_names`, ClickHouse Connect выполнит «предзапрос» для получения всех типов столбцов таблицы.
column_type_names	Sequence of ClickHouse type names	None	Список имён типов данных ClickHouse. Если не указаны ни `column_types`, ни `column_type_names`, ClickHouse Connect выполнит «предзапрос» для получения всех типов столбцов таблицы.
column_oriented	bool	False	Если `True`, аргумент `data` считается последовательностью столбцов (и «поворот» данных для вставки не потребуется). В противном случае `data` интерпретируется как последовательность строк.
settings	dict	None	См. описание параметра settings.
context	InsertContext	None	Повторно используемый объект `InsertContext` может применяться для инкапсуляции вышеперечисленных аргументов метода. См. Расширенная вставка (InsertContexts).
transport_settings	dict	None	Необязательный словарь настроек транспортного уровня (HTTP-заголовки и т. п.).

Этот метод возвращает словарь — «сводку запроса» (query summary), как описано в разделе о методе command. Если вставка по какой-либо причине завершится неудачей, будет выброшено исключение.

Для специализированных методов вставки, работающих с Pandas DataFrames, PyArrow Tables и DataFrames на базе Arrow, см. Расширенная вставка (специализированные методы вставки).

Примечание

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

Примеры

В примерах ниже предполагается, что уже существует таблица users со схемой (id UInt32, name String, age UInt8).

Базовая вставка в построчном формате

import clickhouse_connect

client = clickhouse_connect.get_client()

# Данные, ориентированные по строкам: каждый внутренний список — это строка \{#row-oriented-data-each-inner-list-is-a-row}
data = [
    [1, "Alice", 25],
    [2, "Bob", 30],
    [3, "Joe", 28],
]

client.insert("users", data, column_names=["id", "name", "age"])

Вставка по столбцам

import clickhouse_connect

client = clickhouse_connect.get_client()

# Данные в колоночном формате: каждый внутренний список — это колонка \{#column-oriented-data-each-inner-list-is-a-column}
data = [
    [1, 2, 3],  # колонка id
    ["Alice", "Bob", "Joe"],  # колонка name
    [25, 30, 28],  # колонка age
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)

Вставка с явным указанием типов столбцов

import clickhouse_connect

client = clickhouse_connect.get_client()

# Полезно, если нужно избежать запроса DESCRIBE к серверу \{#useful-when-you-want-to-avoid-a-describe-query-to-the-server}
data = [
    [1, "Alice", 25],
    [2, "Bob", 30],
    [3, "Joe", 28],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)

Вставка в конкретную базу данных

import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [1, "Alice", 25],
    [2, "Bob", 30],
]

# Вставка данных в таблицу указанной базы данных \{#insert-into-a-table-in-a-specific-database}
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)

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

Для вставки данных напрямую из файлов в таблицы ClickHouse см. раздел Расширенные методы вставки (вставка из файлов).

Низкоуровневый API

Для продвинутых сценариев использования, где требуется прямой доступ к HTTP-интерфейсам ClickHouse без преобразования типов, см. раздел Расширенное использование (низкоуровневый API).

Вспомогательные классы и функции

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

Обертка AsyncClient

Сведения об использовании обертки AsyncClient в asyncio-средах см. в разделе Расширенное использование (обертка AsyncClient).

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

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

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

Информацию о настройке пула HTTP‑соединений для крупных многопоточных приложений см. в разделе Расширенное использование (настройка пула HTTP‑соединений).

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

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

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

Аргумент settings​

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

Жизненный цикл клиента и рекомендации по использованию​

Основные принципы​

Базовые шаблоны​

Многопоточные приложения​

Корректная очистка​

Когда использовать несколько клиентов​

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

Аргумент parameters​

Привязка на стороне сервера​

Привязка на стороне клиента​

Аргумент settings​

Метод клиента command​

Примеры команд​

Операторы DDL​

Простые запросы, возвращающие одно значение​

Команды с параметрами​

Команды с настройками​

Метод клиента query​

Примеры запросов​

Простой запрос​

Доступ к результатам запроса​

Запрос с клиентскими параметрами​

Запрос с серверными параметрами​

Запрос с параметрами​

Объект QueryResult​

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

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

Метод клиента insert​

Примеры​

Базовая вставка в построчном формате​

Вставка по столбцам​

Вставка с явным указанием типов столбцов​

Вставка в конкретную базу данных​

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

Низкоуровневый API​

Вспомогательные классы и функции​

Исключения​

Утилиты ClickHouse SQL​

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

Обертка AsyncClient​

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

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

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

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

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

Аргумент settings

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

Жизненный цикл клиента и рекомендации по использованию

Основные принципы

Базовые шаблоны

Многопоточные приложения

Корректная очистка

Когда использовать несколько клиентов

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

Аргумент parameters

Привязка на стороне сервера

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

Аргумент settings

Метод клиента `command`

Примеры команд

Операторы DDL

Простые запросы, возвращающие одно значение

Команды с параметрами

Команды с настройками

Метод клиента `query`

Примеры запросов

Простой запрос

Доступ к результатам запроса

Запрос с клиентскими параметрами

Запрос с серверными параметрами

Запрос с параметрами

Объект `QueryResult`

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

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

Метод клиента `insert`

Примеры

Базовая вставка в построчном формате

Вставка по столбцам

Вставка с явным указанием типов столбцов

Вставка в конкретную базу данных

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

Низкоуровневый API

Вспомогательные классы и функции

Исключения

Утилиты ClickHouse SQL

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

Обертка AsyncClient

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

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