Продвинутое использование

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

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

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

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

Параметр	Тип	Значение по умолчанию	Описание
query	str	Required	Любой корректный запрос ClickHouse
parameters	dict or iterable	None	См. описание параметра `parameters`.
settings	dict	None	См. описание параметра `settings`.
fmt	str	None	Формат вывода ClickHouse для возвращаемых байтов. (Если не указан, ClickHouse использует TSV.)
use_database	bool	True	Использовать назначенную клиентом ClickHouse Connect базу данных в качестве контекста запроса
external_data	ExternalData	None	Объект ExternalData, содержащий файловые или бинарные данные для использования в запросе. См. Advanced Queries (External Data)

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

Parameter	Type	Default	Description
table	str	Required	Простое имя таблицы или полное имя таблицы с указанием базы данных
column_names	Sequence[str]	None	Имена столбцов для блока вставки. Обязателен, если параметр `fmt` не включает имена
insert_block	str, bytes, Generator[bytes], BinaryIO	Required	Данные для вставки. Строки будут закодированы в соответствии с кодировкой клиента.
settings	dict	None	См. описание настроек.
fmt	str	None	Формат ввода ClickHouse (Input Format) для байтов `insert_block`. (Если не указан, ClickHouse использует TSV)

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

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

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

import clickhouse_connect

if __name__ == '__main__':
    client = clickhouse_connect.get_client()
    query = 'SELECT number, toString(number) AS number_as_str FROM system.numbers LIMIT 5'
    fmt = 'CSVWithNames'  # or CSV, or CSVWithNamesAndTypes, or TabSeparated, etc.
    stream = client.raw_stream(query=query, fmt=fmt)
    with open("output.csv", "wb") as f:
        for chunk in stream:
            f.write(chunk)

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

"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"

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

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

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

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

Кроме того, в приложении, в котором два или более запросов и/или вставок выполняются «на лету» одновременно, необходимо учитывать ещё два аспекта. Первый — это «сессия» ClickHouse, связанная с запросом/вставкой, а второй — пул HTTP‑соединений, используемый экземплярами клиента ClickHouse Connect.

Обёртка AsyncClient

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

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

import asyncio

import clickhouse_connect


async def main():
    client = await clickhouse_connect.get_async_client()
    result = await client.query("SELECT name FROM system.databases LIMIT 1")
    print(result.result_rows)
    # Результат:
    # [('INFORMATION_SCHEMA',)]

asyncio.run(main())

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

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

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

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

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

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

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

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

Создайте отдельный экземпляр Client для каждого потока/процесса/обработчика событий, которому требуется изоляция сессий. Это сохраняет состояние сессии для каждого клиента (временные таблицы и значения SET).
Используйте уникальный session_id для каждого запроса через аргумент settings при вызове query, command или insert, если вам не требуется общее состояние сессии.
Отключите сессии для общего клиента, установив autogenerate_session_id=False перед созданием клиента (или передайте его напрямую в get_client).

from clickhouse_connect import common
import clickhouse_connect

common.set_setting('autogenerate_session_id', False)  # Необходимо установить перед созданием клиента
client = clickhouse_connect.get_client(host='somehost.com', user='dbuser', password=1234)

В качестве альтернативы передайте autogenerate_session_id=False напрямую в get_client(...).

В этом случае ClickHouse Connect не отправляет session_id, и сервер не будет считать отдельные запросы принадлежащими одному сеансу. Временные таблицы и параметры сеанса не будут сохраняться между запросами.

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

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

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

import clickhouse_connect
from clickhouse_connect.driver import httputil

big_pool_mgr = httputil.get_pool_manager(maxsize=16, num_pools=12)

client1 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)
client2 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)

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

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

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

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

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

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

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

Обёртка AsyncClient​

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

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