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

> 用于将 Python 连接到 ClickHouse 的 ClickHouse Connect 项目套件

# 简介

ClickHouse Connect 是一个核心数据库驱动，可与多种 Python 应用实现互操作。

* 主要接口是 `clickhouse_connect.driver` 中的同步 `Client` 和基于原生 aiohttp 的 `AsyncClient`。该驱动包还提供查询和 insert 上下文、流式辅助工具、DB-API 支持，以及更底层的 HTTP 方法。
* `clickhouse_connect.datatypes` 包使用 ClickHouse Native 二进制列式格式对 ClickHouse 类型进行序列化和反序列化。
* `clickhouse_connect.driverc` 中的可选 Cython 扩展可加速常见的序列化、转换和 buffering 路径。在无法构建这些扩展的平台上，仍可使用 pure Python 路径。
* 该包附带 PEP 561 类型信息，因此下游类型检查器可使用公共驱动、DB-API 和 SQLAlchemy 接口的 annotations。
* `clickhouse_connect.cc_sqlalchemy` 中的 [SQLAlchemy](https://www.sqlalchemy.org/) dialect 支持 SQLAlchemy Core、schema reflection、ClickHouse 特有的查询 clauses 和 table engines，以及 Alembic migrations。基础的 ORM reads 和 inserts 可以正常工作，但该 dialect 的设计目标是分析型 workloads，而非完整的工作单元式 ORM 行为。
* 核心驱动和 [ClickHouse Connect SQLAlchemy](/zh/integrations/language-clients/python/sqlalchemy) 实现是将 ClickHouse 连接到 Apache Superset 的首选方法。请使用 `ClickHouse Connect` 数据库 connection，或 `clickhousedb` SQLAlchemy dialect connection string。

本文档内容截至 clickhouse-connect 1.6.0。若你正从 0.15.x 或更早版本升级，请参阅 [1.0 migration guide](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md)。

<Note>
  标准的 ClickHouse Connect clients 使用 HTTP interface。这支持 HTTP load balancers、proxies 以及常见的企业网络控制。ClickHouse Connect 还提供一个 Experimental 的 in-process [chDB](#embedded-chdb-backend) 后端。
</Note>

<div id="requirements-and-compatibility">
  ## 要求与兼容性
</div>

| 组件         | 支持的版本                                                 |
| ---------- | ----------------------------------------------------- |
| Python     | 3.10 至 3.14。实验性支持 3.14t 这类 free-threaded 构建。          |
| ClickHouse | 当前仍受支持的 ClickHouse 发行版。CI 会针对较新的长期支持版和稳定版本服务器发行版进行测试。 |
| SQLAlchemy | 1.4.40 或更高版本，但低于 3.0                                  |
| Pandas     | 2.x 和 3.x                                             |
| Polars     | 1.0 或更高版本                                             |
| aiohttp    | 3.9 或更高版本                                             |
| 平台         | Linux、macOS 和 Windows，支持范围限于各 Python 版本已发布 wheel 的架构  |

该软件包在可用时会提供已编译的 wheel；如果无法构建 Cython 扩展，则会回退为纯 Python 实现。PyArrow 支持 Python 3.10 至 3.14。Python 3.14 需要 PyArrow 22 或更高版本。

<div id="installation">
  ## 安装
</div>

通过 pip 从 [PyPI](https://pypi.org/project/clickhouse-connect/) 安装 ClickHouse Connect：

```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 也可以从源码安装：

* 对 [GitHub repository](https://github.com/ClickHouse/clickhouse-connect) 执行 `git clone`。
* 切换到项目根目录并运行 `pip install .`。构建系统会自动安装 Cython，以编译可选的 C 扩展。

已安装的版本可通过 `clickhouse_connect.__version__` 查看。

<div id="support-policy">
  ## 支持策略
</div>

在报告问题前，请先更新到最新的 ClickHouse Connect 发行版。请在 [GitHub 项目](https://github.com/ClickHouse/clickhouse-connect/issues)中提交 issue。ClickHouse Connect 以每个驱动发行版发布时[仍受积极支持的 ClickHouse 发行版](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md)为目标。它通常也兼容较旧的服务器版本，但较新的数据类型和协议功能可能需要更新的服务器版本。

<div id="basic-usage">
  ## 基本用法
</div>

<div id="gather-your-connection-details">
  ### 准备连接详情
</div>

要通过 HTTP(S) 连接到 ClickHouse，你需要以下信息：

| Parameter(s)              | Description                                |
| ------------------------- | ------------------------------------------ |
| `HOST` and `PORT`         | 通常，使用 TLS 时端口为 8443；不使用 TLS 时端口为 8123。     |
| `DATABASE NAME`           | 默认情况下，存在一个名为 `default` 的数据库。请使用你要连接的数据库名称。 |
| `USERNAME` and `PASSWORD` | 默认情况下，用户名为 `default`。请根据你的使用场景使用相应的用户名。    |

你的 ClickHouse Cloud 服务的连接信息可在 ClickHouse Cloud 控制台中查看。
选择一个服务，然后点击 **Connect**：

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=119293dc89fd9bb8fa178d0bec957ecc" alt="ClickHouse Cloud 服务连接按钮" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
  </Frame>
</div>

选择 **HTTPS**。连接信息会显示在示例 `curl` 命令中。

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=16a5a08d3a2c44601d981b9ee5a75216" alt="ClickHouse Cloud HTTPS 连接信息" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
  </Frame>
</div>

如果你使用的是自管理 ClickHouse，则连接信息由你的 ClickHouse 管理员配置。

<div id="establish-a-connection">
  ### 建立连接
</div>

下面展示了两个连接到 ClickHouse 的示例：

* 连接到 localhost 上的 ClickHouse 服务器。
* 连接到 ClickHouse Cloud 服务。

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### 使用 ClickHouse Connect 客户端实例连接到 localhost 上运行的 ClickHouse 服务器：
</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)
# Output: [(2000, -50.9035)]

client.close()
```

<div id="embedded-chdb-backend">
  ## 嵌入式 chDB 后端
</div>

Experimental chDB 后端可在 Python 进程内直接运行 ClickHouse 查询，无需 HTTP 服务器。安装 `chdb` 扩展包，然后通过 `interface="chdb"` 或 `chdb://` DSN 选择该后端：

```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 每个进程只支持一个 engine path。它不支持异步客户端或外部数据。