> ## 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. > Пакет проектов 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` ускоряют типовые пути сериализации, преобразования и буферизации. На платформах, где эти расширения нельзя собрать, по-прежнему доступен вариант на чистом Python. Экспериментальный подключаемый [кодек на Rust](/ru/integrations/language-clients/python/rust-codec) может полностью заменить обработку формата Native. * Пакет поставляется с информацией о типах PEP 561, поэтому последующие инструменты проверки типов учитывают аннотации для публичного интерфейса драйвера, DB-API и поверхностей SQLAlchemy. * Диалекты [SQLAlchemy](https://www.sqlalchemy.org/) в `clickhouse_connect.cc_sqlalchemy` включают синхронные соединения `clickhousedb://` и асинхронные соединения `clickhousedb+async://`. Они поддерживают SQLAlchemy Core, отражение схемы, специфичные для ClickHouse секции запросов и движки таблиц, а также миграции Alembic. Базовые операции чтения и вставки ORM работают, но диалект рассчитан на аналитические рабочие нагрузки, а не на полноценную ORM-модель unit-of-work. * Основной драйвер и реализация [ClickHouse Connect SQLAlchemy](/ru/integrations/language-clients/python/sqlalchemy) — предпочтительный способ подключения ClickHouse к Apache Superset. Используйте подключение к базе данных `ClickHouse Connect` или строку подключения диалекта SQLAlchemy `clickhousedb`. Если вы обновляетесь с версии 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 — для синхронного диалекта; 2.0.44 или новее, но ниже 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 ``` Дополнительные интеграции устанавливаются через дополнительные модули: ```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[sqlalchemy-async]" # Async SQLAlchemy dialect pip install "clickhouse-connect[alembic]" # SQLAlchemy and Alembic pip install "clickhouse-connect[chdb]" # Embedded chDB backend pip install "clickhouse-connect[rust,arrow]" # Experimental Rust codec evaluation setup 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-расширений.

Режимы сборки из исходного кода

Сборка из исходного кода поддерживает три режима. Режим по умолчанию и обязательный режим завершаются с ошибкой, если Cython недоступен или `cythonize()` не отрабатывает. Режим пропуска не импортирует Cython. | Режим | Команда | Поведение | | - | - | - | | По умолчанию | `pip install .` | Пытается скомпилировать расширения на C. Если компилятор или компоновщик завершается с ошибкой, сборка откатывается к установке на чистом Python. | | Чистый Python | `CLICKHOUSE_CONNECT_SKIP_CYTHON=1 pip install .` | Собирает пакет на чистом Python, не пытаясь собрать расширения. | | Обязательный | `CLICKHOUSE_CONNECT_REQUIRE_C=1 pip install .` | Сборка завершается с ошибкой, если расширения не удаётся скомпилировать. Рекомендуется для CI и для сборки распространяемых wheel-пакетов. | Одновременная установка `CLICKHOUSE_CONNECT_SKIP_CYTHON=1` и `CLICKHOUSE_CONNECT_REQUIRE_C=1` является ошибкой. Резервные wheel-пакеты, создаваемые по умолчанию, не содержат скомпилированных расширений, но сохраняют теги платформы и интерпретатора. Только режим пропуска создаёт `py3-none-any`. `pip` может закэшировать резервный wheel-пакет, собранный из sdist из индекса, и повторно использовать его для совместимой версии Python и платформы уже после того, как проблема с компилятором будет устранена. Очистите кэш с помощью: ```bash theme={null} pip cache remove clickhouse_connect ``` Проверьте, присутствуют ли все три extension-модуля. Если да, будет выведено `True`: ```bash theme={null} python -c "from importlib.util import find_spec; print(all(find_spec(m) for m in ('clickhouse_connect.driverc.buffer', 'clickhouse_connect.driverc.dataconv', 'clickhouse_connect.driverc.npconv')))" ``` Прямой импорт `clickhouse_connect.driverc.npconv` также требует установленного NumPy. Установленная версия доступна в `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**:
Кнопка подключения сервиса ClickHouse Cloud
Выберите **HTTPS**. Сведения о подключении будут показаны в примере команды `curl`.
Сведения о подключении к ClickHouse Cloud по HTTPS
Если вы используете самоуправляемый 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-клиент и внешние данные не поддерживаются.