> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Пакет проектов ClickHouse Connect для подключения Python к ClickHouse
# Введение
ClickHouse Connect — это основной драйвер для подключения к базе данных, обеспечивающий совместимость с широким спектром Python-приложений.
* Основные интерфейсы — синхронный `Client` и нативный `AsyncClient` на базе aiohttp в `clickhouse_connect.driver`. Пакет драйвера также предоставляет контексты запросов и вставки, вспомогательные средства для стриминга, поддержку DB-API и низкоуровневые HTTP-методы.
* Пакет `clickhouse_connect.datatypes` сериализует и десериализует типы ClickHouse, используя бинарный столбцовый формат ClickHouse Native.
* Необязательные расширения Cython в `clickhouse_connect.driverc` ускоряют типовые пути сериализации, преобразования и буферизации. На платформах, где эти расширения нельзя собрать, по-прежнему доступен вариант на pure Python.
* Пакет поставляется с информацией о типах PEP 561, поэтому последующие инструменты проверки типов учитывают аннотации для публичного интерфейса драйвера, DB-API и поверхностей SQLAlchemy.
* Диалект [SQLAlchemy](https://www.sqlalchemy.org/) в `clickhouse_connect.cc_sqlalchemy` поддерживает SQLAlchemy Core, отражение схемы, специфичные для ClickHouse секции запросов и движки таблиц, а также миграции Alembic. Базовые операции чтения и вставки ORM работают, но диалект рассчитан на аналитические рабочие нагрузки, а не на полноценную ORM-модель unit-of-work.
* Основной драйвер и реализация [ClickHouse Connect SQLAlchemy](/docs/ru/integrations/language-clients/python/sqlalchemy) — предпочтительный способ подключения ClickHouse к Apache Superset. Используйте подключение к базе данных `ClickHouse Connect` или строку подключения диалекта SQLAlchemy `clickhousedb`.
Эта документация актуальна для clickhouse-connect 1.6.0. Если вы обновляетесь с версии 0.15.x или более ранней, см. [руководство по миграции на 1.0](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md).
Стандартные клиенты ClickHouse Connect используют HTTP-интерфейс. Это позволяет работать с HTTP-балансировщиками нагрузки, прокси и распространёнными корпоративными средствами управления сетью. ClickHouse Connect также поддерживает экспериментальный backend chDB, работающий in-process [chDB](#embedded-chdb-backend).
## Требования и совместимость
| Компонент | Поддерживаемые версии |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| Python | От 3.10 до 3.14. Сборки без GIL, такие как 3.14t, поддерживаются в экспериментальном режиме. |
| ClickHouse | Актуальные поддерживаемые релизы ClickHouse. В CI выполняется тестирование на последних LTS- и стабильных релизах сервера. |
| SQLAlchemy | 1.4.40 или новее, ниже 3.0 |
| Pandas | 2.x и 3.x |
| Polars | 1.0 или новее |
| aiohttp | 3.9 или новее |
| Платформы | Linux, macOS и Windows на архитектурах wheel-пакетов, опубликованных для каждой версии Python |
Пакет включает скомпилированные wheel-пакеты там, где они доступны, и использует реализацию на чистом Python, если расширения Cython не удаётся собрать. PyArrow поддерживается для Python 3.10–3.14. Для Python 3.14 требуется PyArrow 22 или новее.
## Установка
Установите ClickHouse Connect из [PyPI](https://pypi.org/project/clickhouse-connect/) с помощью команды pip:
```bash theme={null}
pip install clickhouse-connect
```
Дополнительные интеграции устанавливаются через extras:
```bash theme={null}
pip install "clickhouse-connect[async]" # Native asyncio client
pip install "clickhouse-connect[pandas]" # Pandas
pip install "clickhouse-connect[arrow]" # PyArrow
pip install "clickhouse-connect[polars]" # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[alembic]" # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]" # Embedded chDB backend
pip install "clickhouse-connect[tzdata]" # IANA time zones on minimal systems
```
ClickHouse Connect также можно установить из исходников:
* Выполните `git clone` [репозитория GitHub](https://github.com/ClickHouse/clickhouse-connect).
* Перейдите в корневой каталог проекта и выполните `pip install .`. Система сборки автоматически устанавливает Cython для компиляции необязательных C-расширений.
Установленную версию можно посмотреть в `clickhouse_connect.__version__`.
## Политика поддержки
Прежде чем сообщать о проблеме, обновите ClickHouse Connect до последнего релиза. Сообщать о проблемах следует в [проекте GitHub](https://github.com/ClickHouse/clickhouse-connect/issues). ClickHouse Connect ориентирован на [активно поддерживаемые релизы ClickHouse](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) на момент выхода каждого релиза драйвера. Он часто работает и с более старыми версиями сервера, но для более новых типов данных и возможностей протокола может потребоваться более новая версия сервера.
## Базовое использование
### Подготовьте сведения о подключении
Чтобы подключиться к ClickHouse по HTTP(S), вам понадобится следующая информация:
| Параметр(ы) | Описание |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `HOST` and `PORT` | Обычно используется порт 8443 при использовании TLS и 8123 без TLS. |
| `DATABASE NAME` | По умолчанию есть база данных `default`; используйте имя базы данных, к которой хотите подключиться. |
| `USERNAME` and `PASSWORD` | По умолчанию имя пользователя — `default`. Используйте имя пользователя, подходящее для вашего сценария использования. |
Сведения о подключении для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud.
Выберите сервис и нажмите **Connect**:
Выберите **HTTPS**. Сведения о подключении будут показаны в примере команды `curl`.
Если вы используете самоуправляемый ClickHouse, сведения о подключении задаёт ваш администратор ClickHouse.
### Установление соединения
Ниже показаны два примера подключения к ClickHouse:
* Подключение к серверу ClickHouse на localhost.
* Подключение к сервису ClickHouse Cloud.
#### Используйте экземпляр клиента ClickHouse Connect для подключения к серверу ClickHouse на localhost:
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client(
host="localhost",
username="default",
password="password",
)
```
#### Используйте экземпляр клиента ClickHouse Connect для подключения к сервису ClickHouse Cloud:
Используйте сведения о подключении, полученные ранее. Для сервисов ClickHouse Cloud требуется TLS, поэтому используйте порт 8443.
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client(
host="HOSTNAME.clickhouse.cloud",
port=8443,
username="default",
password="your password",
)
```
### Взаимодействие с базой данных
Чтобы выполнить команду 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)
# Output: [(2000, -50.9035)]
client.close()
```
## Встроенный backend chDB
Экспериментальный backend chDB выполняет запросы ClickHouse внутри процесса Python без HTTP-сервера. Установите дополнительный модуль `chdb`, затем выберите backend через `interface="chdb"` или DSN `chdb://`:
```python theme={null}
import clickhouse_connect
with clickhouse_connect.get_client(interface="chdb") as client:
result = client.query("SELECT number FROM numbers(3)")
print(result.result_rows)
# Output: [(0,), (1,), (2,)]
```
База данных по умолчанию находится в памяти. Передайте `path="/data/my_chdb"` или используйте `dsn="chdb:///data/my_chdb"` для постоянного хранения. chDB поддерживает только один путь движка для каждого процесса. Async-клиент и внешние данные не поддерживаются.
