简介

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 dialect 支持 SQLAlchemy Core、schema reflection、ClickHouse 特有的查询 clauses 和 table engines，以及 Alembic migrations。基础的 ORM reads 和 inserts 可以正常工作，但该 dialect 的设计目标是分析型 workloads，而非完整的工作单元式 ORM 行为。
• 核心驱动和 ClickHouse Connect SQLAlchemy 实现是将 ClickHouse 连接到 Apache Superset 的首选方法。请使用 ClickHouse Connect 数据库 connection，或 clickhousedb SQLAlchemy dialect connection string。

本文档内容截至 clickhouse-connect 1.6.0。若你正从 0.15.x 或更早版本升级，请参阅 1.0 migration guide。

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

通过 pip 从 PyPI 安装 ClickHouse Connect：

pip install clickhouse-connect

可选集成可通过 extras 安装：

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 执行 git clone。
• 切换到项目根目录并运行 pip install .。构建系统会自动安装 Cython，以编译可选的 C 扩展。

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

在报告问题前，请先更新到最新的 ClickHouse Connect 发行版。请在 GitHub 项目中提交 issue。ClickHouse Connect 以每个驱动发行版发布时仍受积极支持的 ClickHouse 发行版为目标。它通常也兼容较旧的服务器版本，但较新的数据类型和协议功能可能需要更新的服务器版本。

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

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

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

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

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

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

import clickhouse_connect

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

import clickhouse_connect

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

要执行 ClickHouse SQL 命令，请使用客户端的 command 方法：

client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)

要插入批次数据，请使用客户端的 insert 方法，并传入一个由行和值组成的二维数组：

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 方法：

result = client.query("SELECT max(key), avg(metric) FROM new_table")
print(result.result_rows)
# Output: [(2000, -50.9035)]

client.close()

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

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。它不支持异步客户端或外部数据。