> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Набор проектов ClickHouse Connect для подключения Python к ClickHouse

# Введение

ClickHouse Connect — это основной драйвер базы данных, обеспечивающий совместимость с широким спектром Python-приложений.

* Основной интерфейс — объект `Client` в пакете `clickhouse_connect.driver`. Этот базовый пакет также включает различные вспомогательные классы и служебные функции для взаимодействия с сервером ClickHouse, а также реализации "context" для расширенного управления запросами вставки и выборки.
* Пакет `clickhouse_connect.datatypes` предоставляет базовую реализацию и подклассы для всех неэкспериментальных типов данных ClickHouse. Его основная функция — сериализация и десериализация данных ClickHouse в бинарный столбцовый формат ClickHouse "Native", который обеспечивает максимально эффективную передачу данных между ClickHouse и клиентскими приложениями.
* Классы Cython/C в пакете `clickhouse_connect.cdriver` оптимизируют некоторые из наиболее распространённых операций сериализации и десериализации, обеспечивая значительно более высокую производительность по сравнению с чистым Python.
* В пакете `clickhouse_connect.cc_sqlalchemy` есть диалект [SQLAlchemy](https://www.sqlalchemy.org/), построенный на основе пакетов `datatypes` и `dbi`. Эта реализация поддерживает возможности SQLAlchemy Core, включая запросы `SELECT` с `JOIN` (`INNER`, `LEFT OUTER`, `FULL OUTER`, `CROSS`), секции `WHERE`, `ORDER BY`, операции `LIMIT`/`OFFSET`, операции `DISTINCT`, операторы легковесного `DELETE` с условиями `WHERE`, отражение таблиц и базовые операции DDL (`CREATE TABLE`, `CREATE`/`DROP DATABASE`). Хотя она не поддерживает расширенные возможности ORM или DDL, она предоставляет надёжные возможности выполнения запросов, подходящие для большинства аналитических рабочих нагрузок в OLAP-ориентированной базе данных ClickHouse.
* Основной драйвер и реализация [ClickHouse Connect SQLAlchemy](/ru/integrations/language-clients/python/sqlalchemy) являются предпочтительным способом подключения ClickHouse к Apache Superset. Используйте подключение к базе данных `ClickHouse Connect` или строку подключения диалекта SQLAlchemy `clickhousedb`.

Эта документация актуальна для версии clickhouse-connect 0.9.2.

<Note>
  Официальный Python-драйвер ClickHouse Connect использует HTTP-протокол для взаимодействия с сервером ClickHouse. Это обеспечивает поддержку HTTP-балансировщиков нагрузки и хорошо работает в корпоративных средах с межсетевыми экранами и прокси, но уступает нативному TCP-протоколу по степени сжатия и производительности, а также не поддерживает некоторые расширенные возможности, такие как отмена запроса. В некоторых сценариях стоит рассмотреть использование одного из [Community Python drivers](/ru/integrations/language-clients/third-party/client-libraries), которые используют нативный TCP-протокол.
</Note>

<div id="requirements-and-compatibility">
  ## Требования и совместимость
</div>

|     Python |    |       Platform¹ |    |      ClickHouse |    | SQLAlchemy² |    | Apache Superset |    | Pandas |    | Polars |    |
| ---------: | :- | --------------: | :- | --------------: | :- | ----------: | :- | --------------: | :- | -----: | :- | -----: | :- |
| 2.x, \<3.9 | ❌  |     Linux (x86) | ✅  |         \<25.x³ | 🟡 |    \<1.4.40 | ❌  |           \<1.4 | ❌  |   ≥1.5 | ✅  |    1.x | ✅  |
|      3.9.x | ✅  | Linux (Aarch64) | ✅  |           25.x³ | 🟡 |     ≥1.4.40 | ✅  |           1.4.x | ✅  |    2.x | ✅  |        |    |
|     3.10.x | ✅  |     macOS (x86) | ✅  |    25.3.x (LTS) | ✅  |        ≥2.x | ✅  |           1.5.x | ✅  |        |    |        |    |
|     3.11.x | ✅  |     macOS (ARM) | ✅  | 25.6.x (Stable) | ✅  |             |    |           2.0.x | ✅  |        |    |        |    |
|     3.12.x | ✅  |         Windows | ✅  | 25.7.x (Stable) | ✅  |             |    |           2.1.x | ✅  |        |    |        |    |
|     3.13.x | ✅  |                 |    |    25.8.x (LTS) | ✅  |             |    |           3.0.x | ✅  |        |    |        |    |
|            |    |                 |    | 25.9.x (Stable) | ✅  |             |    |                 |    |        |    |        |    |

¹ClickHouse Connect был протестирован на перечисленных платформах. Кроме того, для всех архитектур, поддерживаемых отличным проектом [`cibuildwheel`](https://cibuildwheel.readthedocs.io/en/stable/), собираются непроверенные бинарные wheel-пакеты (с оптимизацией на C). Наконец, поскольку ClickHouse Connect может работать и в режиме pure Python, установка из исходного кода должна работать в любой современной среде Python.

²Поддержка SQLAlchemy ограничена функциональностью Core (запросы, базовый DDL). Возможности ORM не поддерживаются. Подробности см. в документации [SQLAlchemy Integration Support](/ru/integrations/language-clients/python/sqlalchemy).

³ClickHouse Connect в целом хорошо работает и с версиями вне официально поддерживаемого диапазона.

<div id="installation">
  ## Установка
</div>

Установите ClickHouse Connect из [PyPI](https://pypi.org/project/clickhouse-connect/) с помощью pip:

`pip install clickhouse-connect`

ClickHouse Connect также можно установить из исходного кода:

* выполните `git clone` [репозитория на GitHub](https://github.com/ClickHouse/clickhouse-connect).
* (Необязательно) выполните `pip install cython`, чтобы собрать пакет и включить оптимизации C/Cython
* перейдите в корневой каталог проекта с помощью `cd` и выполните `pip install .`

<div id="support-policy">
  ## Политика поддержки
</div>

Пожалуйста, обновите ClickHouse Connect до последней версии, прежде чем сообщать о каких-либо проблемах. О проблемах следует сообщать в [репозиторий GitHub](https://github.com/ClickHouse/clickhouse-connect/issues). Ожидается, что будущие релизы ClickHouse Connect будут совместимы с версиями ClickHouse, которые на момент релиза находятся на активной поддержке. Актуальный список версий сервера ClickHouse, находящихся на активной поддержке, можно найти [здесь](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). Если вы не уверены, какую версию сервера ClickHouse использовать, ознакомьтесь с этим обсуждением [здесь](/ru/resources/support-center/knowledge-base/setup-installation/production#how-to-choose-between-clickhouse-releases). Наша матрица CI тестирует две последние LTS-версии и три последние стабильные версии. Однако благодаря HTTP-протоколу и минимальному количеству ломающих изменений между релизами ClickHouse, ClickHouse Connect обычно хорошо работает и с версиями сервера за пределами официально поддерживаемого диапазона, хотя совместимость с некоторыми расширенными типами данных может различаться.

<div id="basic-usage">
  ## Базовое использование
</div>

<div id="gather-your-connection-details">
  ### Подготовьте сведения о подключении
</div>

Чтобы подключиться к ClickHouse по HTTP(S), вам понадобится следующая информация:

| Параметр(ы)               | Описание                                                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `HOST` and `PORT`         | Обычно используется порт 8443 при использовании TLS и 8123 без TLS.                                                    |
| `DATABASE NAME`           | По умолчанию есть база данных `default`; используйте имя базы данных, к которой хотите подключиться.                   |
| `USERNAME` and `PASSWORD` | По умолчанию имя пользователя — `default`. Используйте имя пользователя, подходящее для вашего сценария использования. |

Сведения о подключении для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud.
Выберите сервис и нажмите **Connect**:

<Image img="/images/_snippets/cloud-connect-button.png" size="md" alt="Кнопка подключения сервиса ClickHouse Cloud" border />

Выберите **HTTPS**. Сведения о подключении будут показаны в примере команды `curl`.

<Image img="/images/_snippets/connection-details-https.png" size="md" alt="Сведения о подключении к ClickHouse Cloud по HTTPS" border />

Если вы используете самоуправляемый ClickHouse, сведения о подключении задаёт ваш администратор ClickHouse.

<div id="establish-a-connection">
  ### Установление соединения
</div>

Ниже показаны два примера подключения к ClickHouse:

* Подключение к серверу ClickHouse на localhost.
* Подключение к сервису ClickHouse Cloud.

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### Используйте экземпляр клиента ClickHouse Connect для подключения к серверу ClickHouse на localhost:
</div>

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', username='default', password='password')
```

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service">
  #### Используйте экземпляр клиента ClickHouse Connect для подключения к сервису ClickHouse Cloud:
</div>

<Tip>
  Используйте сведения о подключении, полученные ранее. Для сервисов ClickHouse Cloud требуется TLS, поэтому используйте порт 8443.
</Tip>

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')
```

<div id="interact-with-your-database">
  ### Работа с базой данных
</div>

Чтобы выполнить команду ClickHouse SQL, используйте метод `command` клиента:

```python theme={null}
client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')
```

Чтобы вставить данные батчем, используйте метод `insert` клиента, передав двумерный массив строк и значений:

```python theme={null}
row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])
```

Чтобы получить данные с помощью ClickHouse SQL, используйте метод `query` клиента:

```python theme={null}
result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Вывод: [(2000, -50.9035)]
```