简介

用于将 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 路径。在无法构建这些扩展的平台上，仍可使用纯 Python 路径。一个需要主动启用的 Experimental Rust codec 可以完全替代 Native format 的处理过程。
• 该包附带 PEP 561 类型信息，因此下游类型检查器可使用公共驱动、DB-API 和 SQLAlchemy 接口的 annotations。
• clickhouse_connect.cc_sqlalchemy 中的 SQLAlchemy dialects 包括同步的 clickhousedb:// 连接和异步的 clickhousedb+async:// 连接。它们支持 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。

若你正从 0.15.x 或更早版本升级，请参阅 1.0 migration guide。

标准的 ClickHouse Connect 客户端 使用 HTTP interface。这支持 HTTP load balancers、proxies 以及常见的企业网络控制。ClickHouse Connect 还提供一个 Experimental 的 in-process chDB 后端。

​

要求与兼容性

组件	支持的版本
Python	3.10 至 3.14。实验性支持 3.14t 这类 free-threaded 构建。
ClickHouse	当前仍受支持的 ClickHouse 发行版。CI 会针对较新的长期支持版和稳定版本服务器发行版进行测试。
SQLAlchemy	同步 dialect 需要 1.4.40 或更高版本 (低于 3.0) ；异步 dialect 需要 2.0.44 或更高版本 (低于 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 或更高版本。

​

安装

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

• 对 GitHub repository 执行 git clone。
• 切换到项目根目录并运行 pip install .。构建系统会自动安装 Cython，以编译可选的 C 扩展。

​

源码构建模式

源码构建支持三种模式。当 Cython 不可用或 cythonize() 失败时，默认模式和 required 模式都会构建失败。skip 模式不会导入 Cython。

模式	命令	行为
默认	pip install .	尝试编译 C 扩展。如果编译器或链接器失败，构建将回退为纯 Python 安装。
纯 Python	CLICKHOUSE_CONNECT_SKIP_CYTHON=1 pip install .	直接构建纯 Python，不尝试编译扩展。
Required	CLICKHOUSE_CONNECT_REQUIRE_C=1 pip install .	如果扩展无法编译，则构建失败。推荐用于 CI 以及构建可分发的 wheel。

同时设置 CLICKHOUSE_CONNECT_SKIP_CYTHON=1 和 CLICKHOUSE_CONNECT_REQUIRE_C=1 会导致错误。

默认回退生成的 wheel 不包含已编译的扩展，但仍保留平台和解释器标签。只有 skip 模式才会生成 py3-none-any。pip 可能会缓存由索引中的 sdist 构建出的回退 wheel，并在编译器问题修复后，仍将其重用于兼容的 Python 版本和平台。可使用以下命令清除缓存：

pip cache remove clickhouse_connect

检查这三个 extension 模块是否都已存在。若都存在，则会输出 True：

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 项目中提交 issue。ClickHouse Connect 以每个驱动发行版发布时仍受积极支持的 ClickHouse 发行版为目标。它通常也兼容较旧的服务器版本，但较新的数据类型和协议功能可能需要更新的服务器版本。

​

基本用法

​

准备连接详情

要通过 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：

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

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

​

建立连接

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

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

​

使用 ClickHouse Connect 客户端实例连接到 localhost 上运行的 ClickHouse 服务器：

import clickhouse_connect

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

​

使用 ClickHouse Connect 客户端实例连接到 ClickHouse Cloud 服务：

使用前面获取的连接信息。ClickHouse Cloud 服务要求使用 TLS，因此请使用 8443 端口。

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()

​

嵌入式 chDB 后端

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