> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > API драйвера ClickHouse Connect # API драйвера ClickHouse Connect Для большинства методов API рекомендуется использовать именованные аргументы, поскольку возможных аргументов много и большинство из них необязательны. *Методы, не описанные здесь, не считаются частью API и могут быть удалены или изменены.*
## Инициализация клиента
Класс `clickhouse_connect.driver.client` предоставляет основной интерфейс между приложением Python и сервером базы данных ClickHouse. Чтобы получить экземпляр Client, используйте функцию `clickhouse_connect.get_client`, которая принимает следующие аргументы:
### Аргументы подключения
| Параметр | Тип | По умолчанию | Описание | | --------------------------- | ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | interface | str | http | Должно быть `http` или `https`. | | host | str | localhost | Имя хоста или IP-адрес сервера ClickHouse. Если не задано, будет использоваться `localhost`. | | port | int | 8123 или 8443 | HTTP- или HTTPS-порт ClickHouse. Если не задан, по умолчанию используется 8123, либо 8443, если *secure*=*True* или *interface*=*https*. | | username | str | default | Имя пользователя ClickHouse. Если не задано, будет использоваться пользователь ClickHouse `default`. | | password | str | *\* | Пароль для *username*. | | database | str | *None* | База данных по умолчанию для соединения. Если не задана, ClickHouse Connect будет использовать базу данных по умолчанию для *username*. | | secure | bool | False | Использовать HTTPS/TLS. Переопределяет значения, автоматически определённые по аргументам interface или port. | | dsn | str | *None* | Строка в стандартном формате DSN (Data Source Name). Другие параметры подключения (например, host или user) будут извлечены из этой строки, если они не заданы явно. | | compress | bool или str | True | Включить сжатие для HTTP-вставок ClickHouse и результатов запросов. См. [Дополнительные параметры (сжатие)](/ru/integrations/language-clients/python/additional-options#compression) | | query\_limit | int | 0 (без ограничений) | Максимальное количество строк, возвращаемых в любом ответе `query`. Установите 0, чтобы возвращать неограниченное число строк. Обратите внимание, что большие лимиты запроса могут привести к исключениям из-за нехватки памяти, если результаты не передаются потоково, поскольку они целиком загружаются в память. | | 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 | *\* | Объект `PoolManager` из библиотеки `urllib3`, который будет использоваться. Полезно в сложных сценариях, где требуется несколько пулов соединений для разных хостов. | | http\_proxy | str | *None* | Адрес HTTP-прокси (эквивалентно установке переменной окружения HTTP\_PROXY). | | https\_proxy | str | *None* | Адрес HTTPS-прокси (эквивалентно установке переменной окружения HTTPS\_PROXY). | | apply\_server\_timezone | bool | True | Использовать часовой пояс сервера для результатов запросов с поддержкой часовых поясов. См. [Приоритет часовых поясов](/ru/integrations/language-clients/python/advanced-querying#time-zones) | | show\_clickhouse\_errors | bool | True | Включать подробные сообщения об ошибках сервера ClickHouse и коды исключений в клиентские исключения. | | autogenerate\_session\_id | bool | *None* | Переопределяет глобальную настройку `autogenerate_session_id`. Если True, автоматически генерирует UUID4-идентификатор сеанса, когда он не задан. | | proxy\_path | str | \ | Необязательный префикс пути, добавляемый к URL сервера ClickHouse при конфигурации через прокси. | | form\_encode\_query\_params | bool | False | Отправлять параметры запроса как данные формы в теле запроса, а не как URL parameters. Полезно для запросов с большими наборами параметров, которые могут превысить ограничение на длину URL. | | rename\_response\_column | str | *None* | Необязательная функция обратного вызова или сопоставление имён столбцов для переименования столбцов в ответе в результатах запроса. |
### Аргументы HTTPS/TLS
| Параметр | Тип | По умолчанию | Описание | | ------------------ | ---- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | verify | bool | True | Проверять TLS/SSL-сертификат сервера ClickHouse (имя хоста, срок действия и т. д.) при использовании HTTPS/TLS. | | ca\_cert | str | *None* | Если *verify*=*True*, путь к файлу корневого сертификата CA для проверки сертификата сервера 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` предполагает аутентификацию ClickHouse с помощью взаимного TLS и клиентского сертификата. Поведение *None*/по умолчанию — `mutual` |
### Аргумент settings
Наконец, аргумент `settings` для `get_client` используется для передачи серверу дополнительных настроек ClickHouse с каждым клиентским запросом. Обратите внимание, что в большинстве случаев пользователи с доступом *readonly*=*1* не могут изменять настройки, передаваемые вместе с запросом, поэтому ClickHouse Connect отбрасывает такие настройки в итоговом запросе и записывает предупреждение в журнал. Следующие настройки применяются только к HTTP-запросам/сеансам, используемым ClickHouse Connect, и не документированы как общие настройки ClickHouse. | Setting | Описание | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | buffer\_size | Размер буфера (в байтах), который сервер ClickHouse использует перед записью в HTTP-канал. | | session\_id | Уникальный идентификатор сеанса для связывания связанных запросов на сервере. Требуется для временных таблиц. | | compress | Нужно ли серверу ClickHouse сжимать данные ответа POST. Эту настройку следует использовать только для «raw»-запросов. | | decompress | Нужно ли распаковывать данные, отправляемые на сервер ClickHouse. Эту настройку следует использовать только для «raw»-вставок. | | quota\_key | Ключ квоты, связанный с этим запросом. См. документацию сервера ClickHouse по квотам. | | session\_check | Используется для проверки состояния сеанса. | | session\_timeout | Количество секунд бездействия, по истечении которых сеанс, определяемый идентификатором сеанса, завершится по тайм-ауту и больше не будет считаться действительным. По умолчанию — 60 секунд. | | wait\_end\_of\_query | Буферизует весь ответ на сервере ClickHouse. Эта настройка необходима для возврата сводной информации и автоматически устанавливается для нестриминговых запросов. | | 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) # Вывод: '22.10.1.98' ``` * Подключение к защищённому (HTTPS) внешнему серверу ClickHouse ```python theme={null} 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' ``` * Подключение с идентификатором сеанса, а также с другими пользовательскими параметрами подключения и настройками ClickHouse. ```python theme={null} 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' ```
## Жизненный цикл клиента и рекомендации
Создание клиента ClickHouse Connect — ресурсоемкая операция, включающая установление соединения, получение метаданных сервера и инициализацию настроек. Следуйте этим рекомендациям для оптимальной производительности:
### Основные принципы
* **Повторно используйте клиенты**: Создавайте клиенты один раз при запуске приложения и используйте их повторно в течение всего жизненного цикла приложения * **Избегайте частого создания**: Не создавайте новый клиент для каждого запроса или обращения (это отнимает сотни миллисекунд на каждую операцию) * **Корректно освобождайте ресурсы**: Всегда закрывайте клиенты при завершении работы, чтобы освободить ресурсы пула соединений * **По возможности используйте совместно**: Один клиент может обрабатывать множество параллельных запросов через свой пул соединений (см. примечания о потоках ниже)
### Основные рекомендации
**✅ Хорошо: повторно используйте один экземпляр клиента** ```python theme={null} import clickhouse_connect # Создаётся один раз при запуске client = clickhouse_connect.get_client(host='my-host', username='default', password='password') # Используется повторно для всех запросов for i in range(1000): result = client.query('SELECT count() FROM users') # Закрывается при завершении работы client.close() ``` **❌ Плохо: повторное создание клиентов** ```python theme={null} # ПЛОХО: создаёт 1000 клиентов с высокими накладными расходами на инициализацию 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`. Чтобы безопасно использовать один клиент в нескольких потоках: ```python theme={null} import clickhouse_connect import threading # Вариант 1: Отключить сеансы (рекомендуется для общих клиентов) 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() # Вывод: # Thread 0: 0 # Thread 7: 7 # Thread 1: 1 # Thread 9: 9 # Thread 4: 4 # Thread 2: 2 # Thread 8: 8 # Thread 5: 5 # Thread 6: 6 # Thread 3: 3 ``` **Альтернатива при использовании сеансов:** Если вам нужны сеансы (например, для временных таблиц), создайте отдельный клиент для каждого потока: ```python theme={null} 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()`, чтобы принудительно очистить сокеты; в противном случае соединения будут автоматически освобождены по истечении периода бездействия и при завершении процесса. ```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 добавляет соответствующие параметры запроса, если обнаруживает выражение привязки вида `{:}`. При использовании привязки на стороне сервера аргумент `parameters` должен быть словарём Python. * Привязка на стороне сервера со словарём 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\'' ``` Привязка на стороне сервера поддерживается (сервером ClickHouse) только для запросов `SELECT`. Она не работает с запросами `ALTER`, `DELETE`, `INSERT` и другими типами запросов. В будущем это может измениться; см. [https://github.com/ClickHouse/ClickHouse/issues/42092](https://github.com/ClickHouse/ClickHouse/issues/42092).
#### Привязка на стороне клиента
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'' ``` Для привязки аргументов DateTime64 (типов ClickHouse с точностью до долей секунды) требуется использовать один из двух специальных подходов: * Оберните значение Python `datetime.datetime` в новый класс DT64Param, например: ```python theme={null} 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` к имени параметра ```python theme={null} query = 'SELECT {p1:DateTime64(3)}, {a1:Array(DateTime(3))}' # Привязка на стороне сервера с использованием словаря parameters={'p1_64': dt_value, 'a1_64': [dt_value1, dt_value2]} ```
### Аргумент 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`, чтобы отправлять SQL-запросы на сервер ClickHouse, которые обычно не возвращают данные или возвращают одно примитивное значение либо массив вместо полного набора данных. Этот метод принимает следующие параметры: | Параметр | Тип | По умолчанию | Описание | | ------------------- | ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cmd | str | *Required* | Оператор ClickHouse SQL, который возвращает одно значение или одну строку значений. | | parameters | dict or iterable | *None* | См. [описание параметра parameters](#parameters-argument). | | data | str or bytes | *None* | Необязательные данные, включаемые в команду как тело POST-запроса. | | settings | dict | *None* | См. [описание параметра settings](#settings-argument). | | 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() # Создать таблицу result = client.command("CREATE TABLE test_command (col_1 String, col_2 DateTime) ENGINE MergeTree ORDER BY tuple()") print(result) # Возвращает QuerySummary с query_id # Показать определение таблицы result = client.command("SHOW CREATE TABLE test_command") print(result) # Вывод: # CREATE TABLE default.test_command # ( # `col_1` String, # `col_2` DateTime # ) # ENGINE = MergeTree # ORDER BY tuple() # Удалить таблицу client.command("DROP TABLE test_command") ```
#### Простые запросы, возвращающие одиночные значения
```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Результат с одним значением count = client.command("SELECT count() FROM system.tables") print(count) # Вывод: 151 # Версия сервера version = client.command("SELECT version()") print(version) # Вывод: "25.8.2.29" ```
#### Команды с параметрами
```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.query` — основной способ получить с сервера ClickHouse один датасет в виде «батча». Он использует нативный формат ClickHouse поверх HTTP для эффективной передачи больших наборов данных (примерно до одного миллиона строк). Этот метод принимает следующие параметры: | Параметр | Тип | По умолчанию | Описание | | --------------------- | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | query | str | *Required* | Запрос ClickHouse SQL типа SELECT или DESCRIBE. | | parameters | dict or iterable | *None* | См. [описание параметров](#parameters-argument). | | settings | dict | *None* | См. [описание настроек](#settings-argument). | | 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* для NULL-значений ClickHouse. Если False, для NULL-значений ClickHouse будет использоваться значение типа по умолчанию (например, 0). Примечание: для NumPy/Pandas по умолчанию используется False из соображений производительности. | | column\_oriented | bool | False | Возвращать результаты как последовательность столбцов, а не строк. Полезно при преобразовании данных Python в другие столбцовые форматы данных. | | query\_tz | str | *None* | Имя часового пояса из базы данных `zoneinfo`. Этот часовой пояс будет применяться ко всем объектам datetime или Pandas Timestamp, возвращаемым запросом. | | column\_tzs | dict | *None* | Словарь, сопоставляющий имена столбцов с именами часовых поясов. Аналогично `query_tz`, но позволяет задавать разные часовые пояса для разных столбцов. | | use\_extended\_dtypes | bool | True | Использовать расширенные dtypes Pandas (например, StringArray), а также pandas.NA и pandas.NaT для значений ClickHouse NULL. Применяется только к методам `query_df` и `query_df_stream`. | | external\_data | ExternalData | *None* | Объект ExternalData, содержащий файлы или бинарные данные для использования в запросе. См. [Advanced Queries (External Data)](/ru/integrations/language-clients/python/advanced-querying#external-data) | | context | QueryContext | *None* | Для инкапсуляции перечисленных выше аргументов метода можно использовать переиспользуемый объект QueryContext. См. [Advanced Queries (QueryContexts)](/ru/integrations/language-clients/python/advanced-querying#querycontexts) | | transport\_settings | dict | *None* | Необязательный словарь HTTP-заголовков, которые нужно включить в этот запрос. Каждая пара ключ-значение добавляется как HTTP-заголовок (например, `{'X-Custom-Header': 'value'}`). Полезно для аутентификации через proxy, трассировки запросов или передачи заголовков, необходимых промежуточной инфраструктуре. |
### Примеры запросов
#### Простой запрос
```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Простой SELECT-запрос result = client.query("SELECT name, database FROM system.tables LIMIT 3") # Получение результатов в виде строк for row in result.result_rows: print(row) # Output: # ('CHARACTER_SETS', 'INFORMATION_SCHEMA') # ('COLLATIONS', 'INFORMATION_SCHEMA') # ('COLUMNS', 'INFORMATION_SCHEMA') # Получение имён и типов столбцов print(result.column_names) # Output: ("name", "database") print([col_type.name for col_type in result.column_types]) # Output: ['String', '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") # Построчный доступ (по умолчанию) print(result.result_rows) # Output: [[0, "0"], [1, "1"], [2, "2"]] # Столбцовый доступ print(result.result_columns) # Output: [[0, 1, 2], ["0", "1", "2"]] # Именованные результаты (список словарей) for row_dict in result.named_results(): print(row_dict) # Output: # {"number": 0, "str": "0"} # {"number": 1, "str": "1"} # {"number": 2, "str": "2"} # Первая строка в виде словаря print(result.first_item) # Output: {"number": 0, "str": "0"} # Первая строка в виде кортежа 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` -- Матрица возвращённых данных в виде последовательности столбцов, где каждый элемент столбца представляет собой последовательность значений строк для этого столбца * `column_names` -- Кортеж строк, содержащий имена столбцов в `result_set` * `column_types` -- Кортеж экземпляров ClickHouseType, представляющих тип данных ClickHouse для каждого столбца в `result_columns` * `query_id` -- `query_id` запроса к ClickHouse (полезно для анализа запроса в таблице `system.query_log`) * `summary` -- Любые данные, возвращённые в заголовке HTTP-ответа `X-ClickHouse-Summary` * `first_item` -- Вспомогательное свойство для получения первой строки ответа в виде словаря (ключи — имена столбцов) * `first_row` -- Вспомогательное свойство, возвращающее первую строку результата * `column_block_stream` -- Генератор результатов запроса в столбцово-ориентированном формате. К этому свойству не следует обращаться напрямую (см. ниже). * `row_block_stream` -- Генератор результатов запроса в построчно-ориентированном формате. К этому свойству не следует обращаться напрямую (см. ниже). * `rows_stream` -- Генератор результатов запроса, который возвращает по одной строке за вызов. К этому свойству не следует обращаться напрямую (см. ниже). * `summary` -- Как описано для метода `command`, словарь со сводной информацией, возвращаемой ClickHouse Свойства `*_stream` возвращают объект Python Context, который можно использовать как итератор для возвращённых данных. Обращаться к ним следует только косвенно, используя методы `*_stream` клиента Client. Подробное описание стриминга результатов запроса (с использованием объектов StreamContext) приведено в разделе [Расширенные запросы (потоковый запрос)](/ru/integrations/language-clients/python/advanced-querying#streaming-queries).
## Получение результатов запросов с помощью 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`. Он принимает следующие параметры: | Параметр | Тип | По умолчанию | Описание | | ------------------- | --------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | table | str | *Обязательно* | Таблица ClickHouse, в которую выполняется вставка. Допускается полное имя таблицы (включая базу данных). | | data | Sequence of Sequences | *Обязательно* | Матрица данных для вставки: либо Sequence строк, каждая из которых представляет собой последовательность значений столбцов, либо Sequence столбцов, каждый из которых представляет собой последовательность значений строк. | | 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` представляет собой Sequence столбцов (и для вставки данных не потребуется транспонирование). В противном случае `data` интерпретируется как Sequence строк. | | settings | dict | *None* | См. [описание settings](#settings-argument). | | context | InsertContext | *None* | Для инкапсуляции приведённых выше аргументов метода можно использовать повторно используемый объект InsertContext. См. [Расширенная вставка (InsertContexts)](/ru/integrations/language-clients/python/advanced-inserting#insertcontexts) | | transport\_settings | dict | *None* | Необязательный словарь HTTP-заголовков, включаемых в этот запрос. Каждая пара ключ-значение добавляется как HTTP-заголовок (например, `{'X-Custom-Header': 'value'}`). Полезно для аутентификации через proxy, трассировки запросов или передачи заголовков, требуемых промежуточной инфраструктурой. | Этот метод возвращает словарь со «сводкой запроса», как описано для метода `command`. Если вставка завершится ошибкой по любой причине, будет вызвано исключение. Описание специализированных методов вставки, работающих с 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() # Данные, ориентированные по строкам: каждый вложенный список — это строка data = [ [1, "Alice", 25], [2, "Bob", 30], [3, "Joe", 28], ] client.insert("users", data, column_names=["id", "name", "age"]) ```
#### Вставка в столбцовом формате
```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Столбцово-ориентированные данные: каждый вложенный список — это столбец 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) ```
#### Вставка с явным указанием типов столбцов
```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Полезно, когда нужно избежать запроса DESCRIBE к серверу 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"], ) ```
#### Вставка в определённую базу данных
```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() data = [ [1, "Alice", 25], [2, "Bob", 30], ] # Вставка в таблицу в указанной базе данных 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).
## Вспомогательные классы и функции
Следующие классы и функции также считаются частью «публичного» API `clickhouse-connect` и, как и классы и методы, описанные выше, остаются стабильными в рамках минорных релизов. Несовместимые изменения в этих классах и функциях будут вноситься только в минорных (а не патч-) релизах, при этом они как минимум в течение одного минорного релиза будут иметь статус устаревших.
### Исключения
Все пользовательские исключения (включая исключения, определённые в спецификации `DB API 2.0`) объявлены в модуле `clickhouse_connect.driver.exceptions`. Исключения, которые фактически обнаруживает драйвер, будут относиться к одному из этих типов.
### Утилиты 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-wrapper).
## Управление идентификаторами сеансов 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).