> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > API драйвера ClickHouse Connect # API драйвера ClickHouse Connect Передавайте именованные аргументы в фабрики client и методы со множеством необязательных параметров. *Методы, не описанные здесь, не считаются частью API и могут быть удалены или изменены.*

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

Используйте `clickhouse_connect.get_client`, чтобы создать синхронный `Client`, или установите дополнительный пакет `async` и вызовите `clickhouse_connect.get_async_client` с `await`, чтобы создать нативный `AsyncClient`.

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

| Параметр | Тип | По умолчанию | Описание | | - | - | - | - | | `interface` | str | `"http"` | `"http"` или `"https"`. Синхронная фабрика также поддерживает экспериментальный бэкенд `"chdb"`. | | `host` | str | `"localhost"` | Хост или IP-адрес сервера ClickHouse. | | `port` | int или None | `8123` или `8443` | По умолчанию используется 8123 для HTTP и 8443 для HTTPS. Передача `None` означает использование значения по умолчанию. | | `username` | str или None | `"default"` | Имя пользователя ClickHouse. Также принимаются псевдонимы `user` и `user_name`. | | `password` | str | `""` | Пароль для `username`. Не сочетайте аутентификацию по имени пользователя и паролю с аутентификацией по токену. | | `access_token` | str или None | `None` | JWT-токен доступа к ClickHouse Cloud. Взаимоисключает использование `token_provider` и аутентификации по имени пользователя и паролю. | | `token_provider` | callable или None | `None` | Вызываемый объект, который предоставляет JWT при первоначальной аутентификации и после её отклонения. Асинхронный провайдер можно использовать с `get_async_client`. | | `database` | str или None | По умолчанию для пользователя | База данных по умолчанию. При передаче `None` запрашивается база данных по умолчанию для пользователя на сервере. | | `secure` | bool или str | `False` | Включает HTTPS/TLS. `interface="https"` также включает HTTPS; то же самое происходит при использовании порта 443 или 8443, если `interface` не задан. | | `dsn` | str или None | `None` | URL подключения. Явные именованные аргументы имеют старшинство над значениями, разобранными из DSN. Используйте процентное кодирование для зарезервированных символов в учетных данных и именах баз данных. | | `settings` | dict или None | `None` | Настройки ClickHouse, применяемые ко всем запросам, отправляемым клиентом. | | `headers` | dict or None | `None` | HTTP-заголовки, применяемые ко всем запросам, включая инициализацию клиента. Пользовательские заголовки применяются после заголовков драйвера по умолчанию и могут их переопределять. | | `compress` | bool or str | `True` | Включите сжатие или укажите `"lz4"`, `"zstd"`, `"br"` или `"gzip"`. См. раздел [Сжатие](/ru/integrations/language-clients/python/additional-options#compression). | | `query_limit` | int | `0` | Ограничение числа строк по умолчанию, добавляемое к подходящим запросам. Ноль означает отсутствие ограничений. Для больших результатов используйте потоковую передачу вместо материализации всего в памяти. | | `query_retries` | int | `2` | Количество повторных попыток при ошибках чтения, допускающих повтор. Команды и операции вставки обычно не повторяются, поскольку повторное выполнение может привести к дублированию побочных эффектов. | | `connect_timeout` | int для синхронного клиента, float для async-клиента | `10` | Тайм-аут установления нового соединения в секундах. Время ожидания свободного слота в пуле соединений не учитывается. Async-клиент принимает дробные значения секунд. | | `send_receive_timeout` | int для синхронного клиента, float для async-клиента | `300` | Тайм-аут чтения из сокета в секундах. Async-клиент принимает дробные значения секунд. | | `client_name` | str или None | `None` | Префикс, добавляемый к HTTP User-Agent для идентификации в `system.query_log`. | | `session_id` | str или None | Генерируется для синхронных клиентов | Явно заданный ID сеанса ClickHouse. У синхронных клиентов он генерируется по умолчанию; у async-клиентов — нет. | | `autogenerate_session_id` | bool или None | Глобальная настройка для синхронных клиентов, `False` — для async-клиентов | Переопределяет автоматическую генерацию ID сеанса. Если состояние сеанса не требуется, отключите это для клиента, используемого несколькими параллельными операциями. | | `autogenerate_query_id` | bool или None | Глобальная настройка, `True` | Переопределяет автоматическую генерацию Query id в формате UUID. | | `http_proxy` | str или None | Переменная окружения/по умолчанию | Адрес HTTP-прокси для клиента. | | `https_proxy` | str или None | Переменная окружения/по умолчанию | Адрес HTTPS-прокси для каждого клиента. | | `pool_mgr` | `urllib3.PoolManager` или None | Общий для процесса | Пользовательский менеджер пула только для синхронного клиента. | | `tz_source` | str или None | `"auto"` | Резервный источник часового пояса для столбцов без метаданных часового пояса: `"auto"`, `"server"` или `"local"`. | | `tz_mode` | str или None | `"naive_utc"` | Политика представления результатов в UTC: `"naive_utc"`, `"aware"` или `"schema"`. См. [Часовые пояса](/ru/integrations/language-clients/python/advanced-querying#time-zones). | | `show_clickhouse_errors` | bool, булева строка, `"scrub"` или None | `True` | Управляет `str(exc)` для ошибок сервера, транспортных ошибок и `StreamFailureError` в середине потока. `True` включает URL запроса и завершающую информацию о версии сервера. `"scrub"` сохраняет текст SQL-ошибки и символьное имя, но удаляет хост/URL и завершающую часть `(version ...)`. `False` возвращает общее сообщение (`code` по-прежнему задаётся для ошибок сервера). Булевы строки допустимы. Другие строки вызывают `ProgrammingError`. Для транспортных ошибок `__cause__` и трассировки стека по-прежнему содержат исходное транспортное исключение. | | `proxy_path` | str | `""` | Префикс пути, добавляемый к URL сервера при маршрутизации через proxy. | | `form_encode_query_params` | bool | `False` | Всегда помещать параметры запроса в тело HTTP-запроса в формате form-encoded. Крупные полезные нагрузки небинарных параметров автоматически переносятся туда, даже если это значение равно false. | | `native_codec` | str или None | Глобальная настройка, `"python"` | Экспериментальный кодек для трафика в формате Native, управляемого клиентом: `"python"`, `"rust"` или `"rust_strict"`. Значения с Rust требуют wheel-пакета `clickhouse-connect-core`. См. [Кодек на Rust](/ru/integrations/language-clients/python/rust-codec). | | `rename_response_column` | str или None | `None` | Стратегия переименования столбцов: `"remove_prefix"`, `"to_camelcase"`, `"to_camelcase_without_prefix"`, `"to_underscore"` или `"to_underscore_without_prefix"`. | И синхронные, и асинхронные HTTP-фабрики преобразуют строковые значения из параметров запроса DSN или `generic_args` для следующих параметров клиента: `connect_timeout`, `send_receive_timeout`, `query_limit` и `query_retries` приводятся к указанным выше числовым типам, а `autogenerate_query_id`, `autogenerate_session_id` и `form_encode_query_params` — к булевым значениям. Если строковое значение одного из этих параметров недопустимо, возникает исключение `ProgrammingError`. Асинхронная фабрика также принимает `connector_limit=100`, `connector_limit_per_host=20` и `keepalive_timeout=30.0` для настройки пула соединений aiohttp. Их можно передать как именованные аргументы, как параметры запроса DSN или через `generic_args`, который внутренне используется для `connect_args` в SQLAlchemy. Строковые значения этих параметров коннектора преобразуются в числовые типы, указанные в документации. Если строковое значение одного из этих параметров недопустимо, возникает исключение `ProgrammingError`. Явно заданные именованные аргументы со значением, отличным от `None`, имеют приоритет над `generic_args`, а те, в свою очередь, — над DSN. Параметр `pool_mgr` не поддерживается. Синхронный backend chDB принимает `path` и `chdb_options`; см. раздел [Встроенный backend chDB](#embedded-chdb-backend).

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

| Параметр | Тип | По умолчанию | Описание | | - | - | - | - | | `verify` | bool or str | `True` | Проверяет сертификат сервера и имя хоста. `verify="proxy"` включает режим прокси TLS. | | `ca_cert` | str or None | `None` | Путь к набору CA. Используйте `"certifi"`, чтобы выбрать набор, поставляемый с пакетом `certifi`. | | `client_cert` | str or None | `None` | PEM-сертификат клиента, включая промежуточные сертификаты, если это требуется. | | `client_cert_key` | str or None | `None` | Путь к закрытому ключу, если ключ не включён в `client_cert`. | | `server_host_name` | str or None | `None` | Имя хоста TLS-сертификата/SNI, если оно отличается от `host`, например при использовании туннеля или частной конечной точки. | | `tls_mode` | str or None | `None` | `"mutual"` использует аутентификацию ClickHouse по схеме взаимного TLS. `"proxy"` и `"strict"` передают сертификат на уровне TLS без включения заголовков аутентификации ClickHouse по сертификату. Значение по умолчанию `None` ведёт себя как `"mutual"`, если предоставлен сертификат клиента. |

Аргумент settings

Наконец, аргумент `settings` для `get_client` используется для передачи серверу дополнительных настроек ClickHouse с каждым клиентским запросом. Обратите внимание, что в большинстве случаев пользователи с доступом *readonly*=*1* не могут изменять настройки, передаваемые вместе с запросом, поэтому ClickHouse Connect отбрасывает такие настройки в итоговом запросе и записывает предупреждение в журнал. Следующие настройки применяются только к HTTP-запросам/сеансам, используемым ClickHouse Connect, и не документированы как общие настройки ClickHouse. | Setting | Описание | | - | - | | `buffer_size` | Размер буфера HTTP-ответа на стороне сервера в байтах. | | `session_id` | Идентификатор сеанса, используемый для связывания связанных запросов. Требуется для временных таблиц и состояния сеанса. | | `compress` | Указывает серверу сжимать HTTP-ответ. Обычно управляется параметром сжатия клиента. | | `decompress` | Указывает серверу распаковывать тело запроса. Используется для предварительно сжатых raw-вставок. | | `quota_key` | Ключ квоты, связанный с запросом. | | `session_check` | Указывает серверу проверить существование сеанса. | | `session_timeout` | Тайм-аут неактивности сеанса в секундах. | | `wait_end_of_query` | Буферизует полный ответ на сервере. Клиент устанавливает этот параметр при необходимости для нестриминговой сводной информации. | | `query_id` | Явный Query id для запроса. | | `client_protocol_version` | Уровень возможностей клиентского протокола в native-формате. Обычно согласовывается автоматически. | | `role` | Роль ClickHouse для использования в запросе/сеансе. | О других настройках ClickHouse, которые можно передавать с каждым запросом, см. [в документации ClickHouse](/ru/reference/settings/session-settings).

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

* Без параметров клиент ClickHouse Connect подключится к HTTP-порту по умолчанию на `localhost` с пользователем по умолчанию `default` и без пароля: ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() print(client.server_version) ``` * Подключение к защищённому (HTTPS) внешнему серверу ClickHouse ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client( host="play.clickhouse.com", secure=True, port=443, username="play", password="clickhouse", ) print(client.command("SELECT timezone()")) ``` * Подключение с идентификатором сеанса, а также с другими пользовательскими параметрами подключения и настройками ClickHouse. ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client( host="play.clickhouse.com", username="play", password="clickhouse", port=443, secure=True, session_id="example_session_1", connect_timeout=15, database="github", settings={"distributed_ddl_task_timeout": 300}, ) print(client.database) # Output: github ```

Встроенное backend-соединение chDB

Установите `clickhouse-connect[chdb]`, чтобы использовать экспериментальное backend-соединение chDB, работающее в процессе приложения. Оно предоставляет синхронные методы клиента: запросы, вставка, стриминг и методы Arrow: ```python theme={null} import clickhouse_connect with clickhouse_connect.get_client(interface="chdb") as client: result = client.query("SELECT sum(number) FROM numbers(10)") print(result.first_row) # Output: (45,) ``` По умолчанию используется база данных в оперативной памяти. Передайте `path="/data/my_chdb"` или используйте `dsn="chdb:///data/my_chdb"` для постоянного хранения данных. Это backend-соединение поддерживает только один путь к движку на процесс и не поддерживает `get_async_client` или внешние данные.

Жизненный цикл клиента и рекомендации

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

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

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

Основные рекомендации

Повторно используйте один экземпляр клиента: ```python theme={null} 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() ``` Избегайте повторного создания клиентов: ```python theme={null} # 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`, если клиент обнаруживает их локальное пересечение. Состояние именованного сеанса и серверные проверки пересечения сеансов действуют только в пределах одного процесса сервера ClickHouse, поэтому фиксированный `session_id` не обеспечивает ни распределённого состояния, ни распределённого мьютекса в ClickHouse Cloud и других развертываниях с балансировкой нагрузки. Чтобы безопасно использовать один клиент в нескольких потоках: ```python theme={null} import clickhouse_connect import threading # 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): # All threads can now safely use the same client 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() ``` **Альтернатива при использовании сеансов:** Если вам нужны сеансы (например, для временных таблиц), создайте отдельный клиент для каждого потока: ```python theme={null} def worker(thread_id): # Each thread gets its own client with isolated session client = clickhouse_connect.get_client( host="my-host", username="default", password="password", ) client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory") # ... use temp table ... client.close() ```

Правильная очистка

Всегда закрывайте клиенты при завершении работы. Обратите внимание: `client.close()` освобождает клиент и закрывает HTTP-соединения из пула только в том случае, если клиент управляет собственным менеджером пула (например, если он создан с пользовательскими параметрами TLS/прокси). Для общего пула по умолчанию используйте `client.close_connections()`, чтобы принудительно очистить сокеты; в противном случае соединения будут автоматически освобождены по истечении периода бездействия и при завершении процесса. ```python theme={null} client = clickhouse_connect.get_client( host="my-host", username="default", password="password", ) try: result = client.query("SELECT 1") finally: client.close() ``` Или используйте контекстный менеджер: ```python theme={null} 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 поддерживает [привязку на стороне сервера](/ru/concepts/features/interfaces/client#cli-queries-with-parameters) для значений в запросе. Привязанное значение передаётся отдельно от запроса в виде HTTP-параметра. ClickHouse Connect использует этот режим, когда обнаруживает выражение в формате `{:}`. Передавайте значения в виде словаря Python. Имена параметров должны быть ASCII-именами ClickHouse BareWord. Драйвер принимает `$` в начале, внутри или в конце имени, если сервер допускает его использование, например `{$tenant_id:String}`. Ключ словаря, который начинается и заканчивается символом `$` и содержит буферное значение, например `bytes`, `bytearray` или `memoryview`, зарезервирован для соглашения ClickHouse Connect об использовании необработанных двоичных параметров. Если такой ключ используется для небинарного параметра с привязкой на стороне сервера, используйте для него только один заполнитель `{name:Type}`. Повторяющиеся имена `$tag$` могут быть разобраны ClickHouse как маркеры heredoc. Используйте Python `None` для допускающих NULL значений. Вложенные значения `None` поддерживаются внутри параметров `Array` и `Tuple`, а также внутри литералов `Map`, когда `dict_parameter_format` имеет значение `"map"`. * Привязка на стороне сервера со словарём Python, значением DateTime и строковым значением ```python theme={null} 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, ) ``` Это эквивалентно: ```sql theme={null} SELECT * FROM my_table WHERE date >= '2022-10-01 15:20:05' AND string ILIKE 'a string with a single quote\'' ``` Привязка на стороне сервера работает с запросами `SELECT` и операторами `INSERT ... VALUES`. Для вставки больших батчей обычных данных лучше использовать `Client.insert`.

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

ClickHouse Connect также поддерживает привязку параметров на стороне клиента, что дает больше гибкости при формировании шаблонизированных SQL-запросов. Для привязки на стороне клиента аргумент `parameters` должен быть словарём или последовательностью. При привязке на стороне клиента для подстановки параметров используется [форматирование строк Python в стиле "printf"](https://docs.python.org/3/library/stdtypes.html#old-string-formatting). Обратите внимание: в отличие от привязки на стороне сервера, привязка на стороне клиента не работает с идентификаторами баз данных, таблиц и столбцов, поскольку форматирование в стиле Python не различает разные типы строк, а для них требуется разное оформление (обратные кавычки или двойные кавычки для идентификаторов базы данных и одинарные кавычки для значений данных). * Пример с Python-словарём, значением DateTime и экранированием строк ```python theme={null} 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, ) ``` В результате на сервере формируется следующий запрос: ```sql theme={null} 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 ```python theme={null} import ipaddress parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe)) client.query( "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s", parameters=parameters, ) ``` В результате на сервере формируется следующий запрос: ```sql theme={null} SELECT * FROM some_table WHERE metric >= 35200.44 AND ip_address = '68.61.4.254' ``` При привязке значения `datetime` без часового пояса интерпретируются как календарное время. Клиент форматирует `datetime` без часового пояса дословно. ClickHouse интерпретирует его в часовом поясе, объявленном в заполнителе на стороне сервера, например `{dt:DateTime('Europe/Berlin')}`, затем в `session_timezone`, если он задан, и наконец в часовом поясе сервера. `datetime` с часовым поясом преобразуется в часовой пояс, объявленный в заполнителе, если он указан, иначе — в часовой пояс сервера, полученный при подключении. Если настройка `session_timezone` отличается от полученного часового пояса сервера, укажите часовой пояс в заполнителе, чтобы сохранить нужный момент времени для значений с часовым поясом. Для временной совместимости с прежним преобразованием в локальный часовой пояс хоста задайте `common.set_setting("naive_datetime_binding", "legacy")` перед привязкой параметров. Чтобы сохранить момент времени, добавьте нужный `tzinfo` к значению `datetime` перед передачей его в качестве параметра. При вставке в столбцы `DateTime` или `DateTime64` через `client.insert` значения `datetime` без часового пояса по умолчанию интерпретируются в локальном часовом поясе процесса. Задайте глобальную настройку `naive_datetime_insert` в значение `"server"`, чтобы интерпретировать их как календарное время в часовом поясе столбца или в часовом поясе сервера, если у столбца он не задан. См. [Объекты datetime без часового пояса](/ru/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects). При нативной вставке в столбцы `Date` и `Date32` используется календарная дата самого значения Python `datetime`, без преобразования часового пояса. Если одна и та же календарная дата нужна и для вставки, и для параметра запроса, явно передавайте `value.date()`. См. [Значения Date и Date32](/ru/integrations/language-clients/python/advanced-inserting#date-and-date32-values). Для заполнителя `{value:DateTime64(precision)}` на стороне сервера объявленный тип автоматически сохраняет точность до долей секунды, в том числе внутри подсказок `Array` и `Tuple`. Привязка `%s` на стороне клиента не имеет объявленного типа. Оберните `datetime` в `DT64Param`, если его нужно выводить с точностью до долей секунды: ```python theme={null} from datetime import datetime from clickhouse_connect.driver.binding import DT64Param query = "SELECT toDateTime64(%s, 6)" parameters = [DT64Param(datetime.now())] client.query(query, parameters=parameters) ``` Для обратной совместимости имя параметра в словаре, оканчивающееся на `_64`, также включает форматирование DateTime64, если точное имя с этим суффиксом отсутствует в запросе. Параметры `datetime.time` и `datetime.timedelta` форматируются как литерал `[-]HH:MM:SS[.ffffff]` для столбцов ClickHouse `Time` и `Time64` в обоих стилях привязки и внутри значений `Array` и `Tuple`. Кавычки добавляет клиент, поэтому не заключайте заполнитель в кавычки в запросе. Значение `timedelta` может быть отрицательным и превышать 24 часа. `Timedelta` из pandas сохраняет наносекунды и форматирует дробную часть из девяти цифр для `Time64(9)`. Информация о часовом поясе в значении `time` с часовым поясом игнорируется, поскольку тип ClickHouse `Time` не поддерживает часовые пояса.

аргумент settings

Все основные методы клиента ClickHouse Connect — "insert" и "select" — принимают необязательный именованный аргумент `settings`, который позволяет передавать [пользовательские настройки](/ru/reference/settings/session-settings) сервера ClickHouse для данного SQL-оператора. Аргумент `settings` должен быть словарём. Каждый элемент должен содержать имя настройки ClickHouse и соответствующее ей значение. Обратите внимание, что при отправке на сервер в качестве параметров запроса значения будут преобразованы в строки. Как и в случае с настройками на уровне клиента, ClickHouse Connect отбрасывает любые настройки, которые сервер помечает как *readonly*=*1*, с соответствующим сообщением в журнале. Настройки, применимые только к запросам через HTTP-интерфейс ClickHouse, всегда допустимы. Эти настройки описаны в [API](#settings-argument) `get_client`. Пример использования настроек ClickHouse: ```python theme={null} 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` для операторов, которые не возвращают табличный набор данных, или для запросов, которые возвращают одно примитивное значение или одну строку. В зависимости от ответа метод возвращает строку, целое число, последовательность строк или `QuerySummary`. Если чтение даёт пустой результирующий набор, возвращается пустая строка. | Параметр | Тип | По умолчанию | Описание | | - | - | - | - | | cmd | str | *Required* | Оператор ClickHouse SQL, который возвращает одно значение или одну строку значений. | | parameters | dict or sequence | *None* | См. [описание параметра parameters](#parameters-argument). | | data | str or bytes | *None* | Необязательные данные, включаемые в команду как тело POST-запроса. | | settings | dict | *None* | См. [описание параметра settings](#settings-argument-1). | | use\_database | bool | True | Использовать базу данных клиента (указанную при создании клиента). False означает, что команда будет использовать базу данных сервера ClickHouse по умолчанию для подключенного пользователя. | | external\_data | ExternalData | *None* | Объект `ExternalData`, содержащий файловые или бинарные данные для использования с запросом. См. [Advanced Queries (External Data)](/ru/integrations/language-clients/python/advanced-querying#external-data) | | transport\_settings | dict | *None* | Необязательный словарь HTTP-заголовков, который включается в этот запрос. Каждая пара ключ-значение добавляется как HTTP-заголовок (например, `{'X-Custom-Header': 'value'}`). Полезно для аутентификации через прокси, трассировки запросов или передачи заголовков, требуемых промежуточной инфраструктурой. |

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

DDL-операторы

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Create a table. A successful DDL returns QuerySummary. summary = client.command( "CREATE TABLE test_command " "(col_1 String, col_2 DateTime) " "ENGINE MergeTree ORDER BY tuple()" ) print(summary.query_id()) # Show table definition result = client.command("SHOW CREATE TABLE test_command") print(result) # Output: # CREATE TABLE default.test_command # ( # `col_1` String, # `col_2` DateTime # ) # ENGINE = MergeTree # ORDER BY tuple() # Drop table client.command("DROP TABLE test_command") ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Single value result count = client.command("SELECT count() FROM system.tables") print(count) # Server version version = client.command("SELECT version()") print(version) ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Использование параметров на стороне клиента table_name = "system" result = client.command( "SELECT count() FROM system.tables WHERE database = %(db)s", parameters={"db": table_name} ) # Использование параметров на стороне сервера result = client.command( "SELECT count() FROM system.tables WHERE database = {db:String}", parameters={"db": "system"} ) ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Выполнение команды с определёнными настройками result = client.command( "OPTIMIZE TABLE large_table FINAL", settings={"optimize_throw_if_noop": 1} ) ```

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

`Client.query` получает табличный набор данных в Native format ClickHouse и возвращает `QueryResult`. Полный результат материализуется при обращении к его свойству. Для результатов, которые не следует хранить в памяти, используйте стриминговый метод. Если клиент обнаруживает в конце запроса `LIMIT 0`, он запрашивает метаданные столбцов в формате JSON. Если ответ содержит строки, клиент выбрасывает исключение `clickhouse_connect.driver.exceptions.InternalError` и не выполняет запрос повторно. Такое возможно с запросами `UNION`, `EXCEPT` или `EXPLAIN`, заканчивающимися на `LIMIT 0`. Для таких запросов используйте [`raw_query`](/ru/integrations/language-clients/python/advanced-usage#client-rawquery-method) с выходным форматом, например `fmt="JSON"`. Метод возвращает `bytes`, которые ваше приложение должно декодировать самостоятельно. Это поведение распространяется на синхронные и асинхронные HTTP-клиенты, а также на клиенты chDB. | Параметр | Тип | По умолчанию | Описание | | - | - | - | - | | `query` | str | Required | запрос к ClickHouse, который возвращает табличный результат, чаще всего `SELECT` или `DESCRIBE`. Может быть опущен, если передан через `context`. | | `parameters` | dict or sequence | `None` | См. [аргумент Parameters](#parameters-argument). | | `settings` | dict | `None` | См. [аргумент Settings](#settings-argument-1). | | `query_formats` | dict | `None` | Формат чтения по типу ClickHouse. См. [Форматы чтения](/ru/integrations/language-clients/python/advanced-querying#read-formats). | | `column_formats` | dict | `None` | Формат чтения по столбцу результата, включая сопоставления форматов для типа Nested. | | `encoding` | str | `None` | Кодирование столбцов String. По умолчанию используется UTF-8. | | `use_none` | bool | `True` | Возвращает `None` для SQL NULL. Если указано false, возвращает значение NULL этого типа по умолчанию. Методы NumPy/Pandas выбирают значения по умолчанию с приоритетом производительности. | | `column_oriented` | bool | `False` | Возвращает результат в виде столбцов, а не строк. | | `use_numpy` | bool | `False` | Считывает совместимые столбцы результата в массивы NumPy внутри `QueryResult`. Если нужен результат в виде одной матрицы NumPy, предпочтительно использовать `query_np`. | | `max_str_len` | int | `0` | При `use_numpy` использует Unicode dtype фиксированной ширины для столбцов String длиной до этого значения. Ноль использует массивы объектов. | | `context` | `QueryContext` | `None` | Контекст запроса для повторного использования. Явно заданные аргументы метода переопределяют значения контекста. | | `query_tz` | str or `tzinfo` | `None` | Часовой пояс, применяемый ко всем столбцам результата `DateTime` и `DateTime64`. | | `column_tzs` | dict | `None` | Сопоставление часовых поясов для отдельных столбцов. | | `external_data` | `ExternalData` | `None` | Внешний файл или бинарные данные. См. [Внешние данные](/ru/integrations/language-clients/python/advanced-querying#external-data). | | `transport_settings` | dict | `None` | HTTP-заголовки, добавляемые к этому запросу. | | `tz_mode` | str | Client default | Переопределение обработки часовых поясов для отдельного запроса: `"naive_utc"`, `"aware"` или `"schema"`. |

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

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Simple SELECT query result = client.query( "SELECT number, toString(number) AS label FROM numbers(3)" ) # Access results as rows for row in result.result_rows: print(row) # Output: # (0, '0') # (1, '1') # (2, '2') # Access column names and types print(result.column_names) # Output: ('number', 'label') print([col_type.name for col_type in result.column_types]) # Output: ['UInt64', 'String'] ```

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

```python theme={null} 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) # Output: [(0, '0'), (1, '1'), (2, '2')] # Column-oriented access print(result.result_columns) # 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': 1, 'str': '1'} # {'number': 2, 'str': '2'} # First row as dictionary print(result.first_item) # Output: {'number': 0, 'str': '0'} # First row as tuple print(result.first_row) # Output: (0, '0') ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Использование параметров словаря (в стиле printf) 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) # Использование параметров кортежа query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s" parameters = ("system", 5) result = client.query(query, parameters=parameters) ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Привязка на стороне сервера (более безопасна, обеспечивает лучшую производительность для SELECT-запросов) 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) ```

Запрос с настройками

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Передать настройки ClickHouse вместе с запросом result = client.query( "SELECT sum(number) FROM numbers(1000000)", settings={ "max_block_size": 100000, "max_execution_time": 30 } ) ```

Объект `QueryResult`

Базовый метод `query` возвращает объект `QueryResult` со следующими публичными свойствами: * `result_rows` -- Матрица результатов, представленная в виде строк. * `result_columns` -- Матрица результатов, представленная в виде столбцов. * `result_set` -- `result_rows` или `result_columns` в зависимости от ориентации запроса. * `column_names` -- Кортеж имен столбцов результата. * `column_types` -- Кортеж объектов `ClickHouseType`. * `row_count` -- Количество материализованных строк результата. * `query_id` -- Query id, указанный или сгенерированный для этого запроса. Пустая строка означает, что он недоступен. * `summary` -- Словарь, декодированный из заголовка ответа `X-ClickHouse-Summary`. * `first_item` -- Первая строка в виде словаря или `None` для пустого результата. * `first_row` -- Первая строка в виде последовательности или `None` для пустого результата. * `column_block_stream`, `row_block_stream` и `rows_stream` -- Внутренние контексты потоков. Вместо них используйте соответствующие стриминговые методы клиента. См. [Стриминговые запросы](/ru/integrations/language-clients/python/advanced-querying#streaming-queries), чтобы узнать о поддерживаемых API `StreamContext`.

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

ClickHouse Connect предоставляет специализированные методы запросов для форматов данных NumPy, Pandas и Arrow. Подробную информацию об использовании этих методов, включая примеры, возможности стриминга и расширенную обработку типов, см. в разделе [Расширенное выполнение запросов (запросы NumPy, Pandas и Arrow)](/ru/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries).

Методы потокового выполнения запросов в клиенте

Для потоковой передачи больших результирующих наборов ClickHouse Connect предоставляет несколько методов. Подробности и примеры см. в разделе [Расширенные запросы (потоковые запросы)](/ru/integrations/language-clients/python/advanced-querying#streaming-queries).

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

Для типичного сценария вставки нескольких записей в ClickHouse предусмотрен метод `Client.insert`. Он принимает следующие параметры: | Parameter | Type | Default | Description | | - | - | - | - | | `table` | str | Обязательно | Целевая таблица. Допускается имя с указанием базы данных. Может быть опущено, если задана через `context`. | | `data` | Sequence of Sequences | Обязательно | Матрица данных в строковом или столбцовом формате. Может быть передана позже через `InsertContext`. | | `column_names` | str or Sequence\[str] | `"*"` | Упорядоченные столбцы. `"*"` запускает запрос метаданных для определения всех столбцов, в которые можно выполнять вставку. | | `database` | str or None | База данных клиента | Целевая база данных, если `table` указана без базы данных. | | `column_types` | Sequence\[`ClickHouseType`] | `None` | Явно заданные типы столбцов. При указании позволяет избежать запроса метаданных. | | `column_type_names` | Sequence\[str] | `None` | Явно заданные имена типов ClickHouse. Альтернатива `column_types`. | | `column_oriented` | bool | `False` | Интерпретировать `data` как столбцы, а не как строки. | | `settings` | dict | `None` | См. [аргумент Settings](#settings-argument-1). | | `context` | `InsertContext` | `None` | Повторно используемый контекст вставки. См. [InsertContexts](/ru/integrations/language-clients/python/advanced-inserting#insertcontexts). | | `transport_settings` | dict | `None` | HTTP-заголовки, добавляемые к этому запросу. | Этот метод возвращает `QuerySummary`. Его словарь `summary` содержит значения, сообщаемые сервером. `written_rows` — это удобное свойство, а `written_bytes()` и `query_id()` возвращают соответствующие значения. При ошибке вставки будет вызвано исключение. Описание специализированных методов вставки, работающих с Pandas DataFrames, PyArrow Tables и DataFrames на базе Arrow, см. в разделе [Расширенная вставка (Специализированные методы вставки)](/ru/integrations/language-clients/python/advanced-inserting#specialized-insert-methods). Массив NumPy является допустимым Sequence of Sequences и может использоваться как аргумент `data` для основного метода `insert`, поэтому специализированный метод не требуется.

Примеры

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

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Row-oriented data: each inner list is a row data = [ [13, "user_1", 25], [79, "user_2", 30], ] client.insert("users", data, column_names=["id", "name", "age"]) ```

Вставка в столбцовом формате

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Column-oriented data: each inner list is a column data = [ [13, 79], # id column ["user_1", "user_2"], # name column [25, 30], # age column ] client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True) ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Useful when you want to avoid a DESCRIBE query to the server data = [ [13, "user_1", 25], [79, "user_2", 30], ] client.insert( "users", data, column_names=["id", "name", "age"], column_type_names=["UInt32", "String", "UInt8"], ) ```

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

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() data = [ [13, "user_1", 25], [79, "user_2", 30], ] # Insert into a table in a specific database client.insert( "users", data, column_names=["id", "name", "age"], database="production", ) ```

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

Чтобы напрямую вставлять данные из файлов в таблицы ClickHouse, см. [Расширенная вставка (вставка из файлов)](/ru/integrations/language-clients/python/advanced-inserting#file-inserts).

Raw API

Для продвинутых сценариев, требующих прямого доступа к HTTP-интерфейсам ClickHouse без преобразования типов, см. [Расширенное использование (Raw API)](/ru/integrations/language-clients/python/advanced-usage#raw-api).

Python DB-API 2.0

Модуль `clickhouse_connect.dbapi` реализует интерфейсы connection и cursor, определённые в PEP 249. Он объявляет уровень API 2.0, `threadsafety=2` и `paramstyle="pyformat"`. Модуль также предоставляет конструкторы типов PEP 249 `Date`, `Time`, `Timestamp` и `Binary`, а также функции `DateFromTicks`, `TimeFromTicks` и `TimestampFromTicks`. Модуль экспортирует иерархию исключений PEP 249: `Warning`, `Error`, `InterfaceError`, `DatabaseError`, `DataError`, `OperationalError`, `IntegrityError`, `InternalError`, `ProgrammingError` и `NotSupportedError`. Это те же объекты классов, что и в `clickhouse_connect.driver.exceptions`, поэтому ошибки драйвера можно перехватывать, импортируя их из любого из этих модулей. Специфичное для драйвера исключение `StreamFailureError` по-прежнему доступно в `clickhouse_connect.driver.exceptions` и является подклассом `OperationalError`. ```python theme={null} from clickhouse_connect import dbapi connection = dbapi.connect( host="localhost", username="default", password="password", database="default", ) cursor = connection.cursor() try: cursor.execute( "SELECT name FROM system.tables " "WHERE database = %(database)s ORDER BY name LIMIT 5", {"database": "system"}, ) print(cursor.description) print(cursor.fetchall()) finally: cursor.close() connection.close() ``` `Cursor.execute` и `Cursor.executemany` принимают дополнительные именованные аргументы `settings` и `query_formats`. `settings` передаёт настройки ClickHouse. `query_formats` применяет форматы чтения по типам ClickHouse, когда оператор возвращает строки, используя то же сопоставление, что и `Client.query`. Оба метода также принимают доступный только по имени аргумент `pyformat_encoded`. Его значение по умолчанию `True` соответствует контракту DB-API `pyformat`. Диалект SQLAlchemy устанавливает его в `False`, когда компилятор оператора генерирует необработанные знаки процента, поэтому приложениям обычно не следует задавать его. Параметризованные операции `Cursor.executemany` выполняются по одному разу для каждого набора параметров, сохраняя семантику привязки SQL и вычисления выражений. При работе через HTTP для каждого набора параметров отправляется отдельный запрос. Если один из последующих наборов параметров завершается с ошибкой, уже выполненные записи остаются закоммиченными. Для таких вставок через `executemany` значение `Cursor.rowcount` равно сумме значений `written_rows`, возвращённых ClickHouse, или `-1`, если это значение недоступно. Для операторов INSERT, отправленных через `Cursor.execute`, возвращается `0`. Форма совместимости `INSERT INTO table (columns) VALUES` без плейсхолдеров использует нативную вставку. Оператор INSERT без плейсхолдеров, заканчивающийся на `VALUES`, вызывает `ProgrammingError`, если его не удаётся распознать как эту форму совместимости. Приложениям, которым требуется явная массовая вставка в формате Native, следует использовать `Client.insert`. `fetchone`, `fetchmany` и `fetchall` считывают текущий материализованный результат. `Cursor.description` определяет `null_ok` по типу каждого столбца результата. Типы, не допускающие NULL, возвращают `False`, а допускающие NULL — `True`, включая обёртки `Nullable`, `Variant` и `Dynamic`. `None` означает, что допустимость NULL неизвестна. Если запрос, начинающийся с `SELECT` или `WITH` без учёта начальных комментариев, не возвращает строк и метаданных столбцов, курсор выполняет запрос метаданных с `LIMIT 0`, чтобы заполнить `description`. Если этот запрос метаданных завершается с ошибкой, `description` остаётся пустым. ClickHouse не поддерживает традиционные транзакции через этот HTTP-интерфейс. `Connection.commit()` и `Connection.rollback()` не выполняют никаких действий. Правила [параллелизма для идентификатора сеанса](/ru/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids) по-прежнему действуют, если соединение используется совместно.

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

Следующие модули предоставляют дополнительные общедоступные вспомогательные средства, используемые клиентскими приложениями. Версия установленного пакета доступна как строка `clickhouse_connect.__version__`.

Исключения

Пользовательские исключения, включая иерархию исключений DB-API 2.0, повторно экспортируемую модулем `clickhouse_connect.dbapi`, определены в `clickhouse_connect.driver.exceptions`. `DatabaseError` и `OperationalError` предоставляют числовой атрибут `code` с кодом ошибки ClickHouse и атрибут `name` с символьным именем, например `UNKNOWN_TABLE`, поэтому приложения могут строить логику на основе `exc.code`, а не разбирать сообщение. `code` задается, даже если `show_clickhouse_errors` отключен, тогда как для `name` требуется отображение подробностей ошибки (`True` или `"scrub"`). Оба имеют значение `None`, когда недоступны, например при ошибках передачи данных. Используйте `show_clickhouse_errors="scrub"`, когда конечные пользователи должны видеть ошибки SQL без информации о хосте или версии сервера. Этот параметр также управляет сообщениями `StreamFailureError` в процессе потоковой передачи и общими сообщениями об ошибках передачи данных. Он влияет только на `str(exc)`. Ошибки передачи данных по-прежнему прикрепляются как `__cause__`, а трассировки стека могут содержать исходные сведения о хосте, URL или текст ошибки библиотеки.

Утилиты ClickHouse SQL

Функции и класс DT64Param в модуле `clickhouse_connect.driver.binding` можно использовать для корректного формирования и экранирования запросов ClickHouse SQL. Аналогично, функции из модуля `clickhouse_connect.driver.parser` можно использовать для разбора названий типов данных ClickHouse.

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

Подробнее об использовании ClickHouse Connect в многопоточных, многопроцессных и асинхронных/событийно-ориентированных приложениях см. в разделе [Расширенное использование (многопоточные, многопроцессные и асинхронные/событийно-ориентированные сценарии использования)](/ru/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases).

AsyncClient

Сведения о непосредственном использовании AsyncClient с asyncio см. в разделе [Расширенное использование (AsyncClient)](/ru/integrations/language-clients/python/advanced-usage#asyncclient).

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

Сведения об управлении идентификаторами сеансов ClickHouse в многопоточных или параллельно работающих приложениях см. в разделе [Расширенное использование (Управление идентификаторами сеансов ClickHouse)](/ru/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids).

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

Сведения о настройке пула HTTP-соединений для крупных многопоточных приложений см. в разделе [Расширенное использование (настройка пула HTTP-соединений)](/ru/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool).