Python怎样操作ClickHouse？clickhouse-driver

看不見的法師

发布时间：2025-08-14 18:47:01

653人浏览过

来源于php中文网

原创

python操作clickhouse最主流且推荐的方式是使用clickhouse-driver库，它基于原生tcp协议实现高效通信，性能优异；2. 其核心优势包括高性能与低延迟、支持异步io、完善的数据类型映射、内置连接池机制以及支持参数化查询，适用于实时数据分析、etl管道、日志分析和ad-hoc查询等场景；3. 常见使用“坑”包括连接未关闭导致资源耗尽、大数据量查询引发oom、datetime64精度丢失及网络小查询累积延迟，优化技巧包括使用连接池、流式读取、批量插入、合理设置超时和sql优化；4. 其他可选库有sqlalchemy-clickhouse（适合orm集成，但性能略低）、clickhouse-connect（现代api，由altinity维护，支持http/tcp）和pyclickhouse（早期库，维护不足，不推荐新项目使用）。

Python怎样操作ClickHouse？clickhouse-driver

Python操作ClickHouse，目前最主流且推荐的方式就是使用

clickhouse-driver

这个库。它提供了高效、原生的连接和数据操作能力，是社区中功能相对完善、性能表现优秀的选择之一。

解决方案

要用Python操作ClickHouse，核心就是围绕

clickhouse-driver

库展开。

首先，你得把它安装到你的环境里：

pip install clickhouse-driver

安装好之后，就可以开始连接和操作了。一个典型的连接和查询流程大概是这样：

立即学习“Python免费学习笔记（深入）”；

from clickhouse_driver import Client

# 建立连接
# 我个人习惯把这些配置放到环境变量或者配置文件里，直接写在代码里不安全也不灵活
client = Client(
    host='your_clickhouse_host',
    port=9364,  # ClickHouse的TCP端口，默认是9000，但有些部署可能是9364，具体看你的配置
    user='your_username',
    password='your_password',
    database='your_database',
    settings={'max_result_rows': 10000} # 比如限制一下返回行数，防止一次性拉太多数据
)

try:
    # 执行查询
    # SELECT 操作
    rows = client.execute('SELECT number, rand() FROM system.numbers LIMIT 5')
    print("SELECT 结果:")
    for row in rows:
        print(row)

    # INSERT 操作
    # 准备数据，通常是列表的列表或者字典的列表
    data_to_insert = [
        (1, 'apple'),
        (2, 'banana'),
        (3, 'orange')
    ]
    # 假设你有一个表叫 `my_table`，包含 `id` (UInt64) 和 `fruit` (String) 字段
    # client.execute('INSERT INTO my_table (id, fruit) VALUES', data_to_insert)
    # print("数据插入成功！")

    # 带参数的查询，这很重要，能防止SQL注入，也能提高性能
    # parameterized_rows = client.execute('SELECT * FROM your_table WHERE id = %s', (123,))
    # print("参数化查询结果:", parameterized_rows)

except Exception as e:
    print(f"操作ClickHouse时发生错误: {e}")
finally:
    # 记得关闭连接，释放资源
    # 在生产环境，通常会用连接池来管理，而不是每次都新建和关闭
    client.disconnect()
    print("连接已关闭。")

clickhouse-driver

对ClickHouse的数据类型映射做得挺好，比如ClickHouse的

DateTime

会被映射成Python的

DateTime

对象，数组类型也会自动转换成Python列表。处理大数据量时，它也能支持流式读取，避免一次性加载所有数据到内存导致OOM。

clickhouse-driver

的核心优势和适用场景是什么？

对我来说，

clickhouse-driver

最大的魅力在于它对ClickHouse原生TCP协议的良好支持。这意味着它不是通过HTTP接口，而是直接与ClickHouse的二进制协议交互，性能上自然是没得说。这种原生性让数据传输效率极高，尤其是在处理海量数据时，这种优势体现得淋漓尽致。

它的核心优势可以归纳几点：

高性能与低延迟：直接使用ClickHouse的二进制协议，减少了中间转换的开销。
异步支持：它内置了对
```
asyncio
```
的支持，如果你在构建高性能、高并发的服务，比如实时数据摄入或查询API，这简直是福音。
完善的数据类型映射：几乎所有ClickHouse的数据类型都能很好地映射到Python类型，减少了开发者的心智负担。
连接池（Connection Pool）：虽然上面代码没有直接展示，但它提供了连接池功能，这在生产环境中至关重要，可以复用连接，避免频繁创建和销毁连接带来的开销。
参数化查询：不仅安全，还能让ClickHouse更好地利用查询缓存。

至于适用场景，我用它比较多的地方包括：

实时数据分析平台：后端Python服务从Kafka消费数据，清洗后批量写入ClickHouse，供前端BI工具或自定义报表展示。
ETL数据管道：作为数据抽取（Extract）、转换（Transform）、加载（Load）流程中的加载环节，将处理好的数据高效地写入ClickHouse。
日志分析系统：将海量日志导入ClickHouse，然后通过Python脚本进行聚合查询和报表生成。
Ad-hoc查询工具：开发一些内部使用的工具，让非技术人员也能通过简单的界面查询ClickHouse数据。

可以说，只要你需要在Python应用中与ClickHouse进行高效、稳定的数据交互，

clickhouse-driver

都是一个非常可靠且值得信赖的选择。

在使用

clickhouse-driver

时，常见的“坑”和性能优化技巧有哪些？

在使用

clickhouse-driver

的过程中，我确实踩过一些“坑”，也总结了一些优化经验。

常见的“坑”：

连接管理不当：
- 忘记关闭连接：每次查询都新建连接而不关闭，会导致资源耗尽，特别是短连接场景。
- 不使用连接池：在并发请求多的服务中，每次都创建新连接会显著增加延迟和服务器压力。我记得有一次，因为没注意批量插入的细节，结果把服务器的CPU跑满了，那真是个教训。
大数据量返回导致内存溢出（OOM）：
- 如果你
```
SELECT * FROM large_table
```
  而不加
```
LIMIT
```
  ，或者结果集实在太大，Python进程可能会因为一次性加载所有数据而崩溃。
- 解决方案是使用
```
stream_result=True
```
  参数进行流式读取，或者在SQL层面进行分页（
```
LIMIT offset, count
```
  ）。
数据类型映射问题：
- ClickHouse的
```
DateTime64
```
  精度比Python的
```
DateTime
```
  高，直接转换可能会丢失精度。需要注意配置
```
driver
```
  的
```
settings
```
  ，比如
```
datetime64_as_datetime=True
```
  确保正确处理。
- ClickHouse的
```
LowCardinality
```
  类型，如果直接返回字符串，可能会有性能开销，可以考虑
```
low_cardinality_as_string=False
```
  让驱动返回内部编码，或者确保查询时已经转换为普通字符串。
网络延迟对小查询的影响：
- 如果你的应用频繁地执行大量小查询（每次只取几行数据），即使
```
clickhouse-driver
```
  很快，网络往返的延迟也会累积起来，成为瓶颈。

性能优化技巧：

Cardify卡片工坊

使用Markdown一键生成精美的小红书知识卡片

下载

拥抱连接池：

clickhouse_driver.connection.ConnectionPool

是你的好朋友。通过它来管理连接，可以大大减少连接建立和关闭的开销，提高并发性能。

from clickhouse_driver.connection import ConnectionPool

pool = ConnectionPool(
    host='your_clickhouse_host',
    port=9000,
    user='your_username',
    password='your_password',
    database='your_database',
    connections_min=5, # 最小连接数
    connections_max=20 # 最大连接数
)

with pool.get_client() as client:
    # 在这里执行你的查询
    rows = client.execute('SELECT 1')
    print(rows)
# client 会自动返回到连接池

批量插入 (Batch Inserts)：插入数据时，尽量将多条数据打包成一个批次进行插入，而不是一条一条地插入。这能显著减少网络往返次数和ClickHouse的写入开销。
```
# data_to_insert 是一个列表，每个元素代表一行数据
# client.execute('INSERT INTO your_table VALUES', data_to_insert)
```
合理使用异步IO：如果你的应用是基于
```
asyncio
```
构建的，
```
clickhouse-driver
```
的异步客户端
```
clickhouse_driver.aiohttp.Client
```
能让你充分利用协程的并发优势，提高吞吐量。
调整驱动设置：
- ```
compress_block_size
```
  ：调整数据块压缩大小，可能会影响传输效率。
- ```
send_timeout
```
  和
```
receive_timeout
```
  ：根据你的网络状况和查询复杂度调整超时时间，避免长时间阻塞。
SQL层面的优化：这其实是ClickHouse本身的问题，但通过Python操作时也要注意。比如避免
```
SELECT *
```
，只选择需要的列；利用分区键和排序键进行高效查询；使用物化视图等。

记住，没有银弹，具体的优化策略需要结合你的业务场景、数据量和ClickHouse集群配置来定。

除了

clickhouse-driver

，还有哪些Python库可以操作ClickHouse，它们各自有什么特点？

当然，Python生态系统里操作ClickHouse的库不止

clickhouse-driver

一个。虽然

clickhouse-driver

是我的首选，但了解其他选项的特点，有助于你在特定场景下做出更合适的选择。

```
sqlalchemy-clickhouse
```
：
- 特点：这个库是
```
SQLAlchemy
```
  的ClickHouse方言。如果你已经习惯了使用ORM（对象关系映射）来操作数据库，或者你的项目已经大量使用了SQLAlchemy，那么
```
sqlalchemy-clickhouse
```
  会让你感到非常亲切。它提供了ORM的便利性，可以像操作其他关系型数据库一样操作ClickHouse。
- 优势：
  - ORM抽象层，降低了直接写SQL的复杂度。
  - 与SQLAlchemy生态无缝集成，可以利用SQLAlchemy的连接池、会话管理等功能。
- 劣势：
  - ORM有时会隐藏ClickHouse的一些独特特性和优化点，比如特定函数、数组操作等，可能需要通过
```
text()
```
    来写原生SQL。
  - 性能上，相较于直接使用
```
clickhouse-driver
```
    的原生协议，可能会有轻微的损耗，因为它通常通过HTTP接口与ClickHouse通信（尽管也可以配置TCP）。
- 适用场景：对ORM依赖较重、对开发效率要求高于极致性能、或者已有SQLAlchemy项目需要接入ClickHouse的场景。
```
clickhouse-connect
```
：
- 特点：这是一个相对较新（或者说近几年才开始活跃）的库，由Altinity（ClickHouse的商业支持公司）开发和维护。它旨在提供一个更现代、更易用的接口，同时保持高性能。它也支持HTTP和TCP两种连接方式。
- 优势：
  - API设计可能更符合现代Python开发习惯，简洁直观。
  - 对ClickHouse新特性支持可能更及时。
  - 提供了
```
insert
```
    、
```
query
```
    等高级函数，简化了操作。
- 劣势：
  - 社区活跃度和历史沉淀可能不如
```
clickhouse-driver
```
    那么久。
- 适用场景：寻求
```
clickhouse-driver
```
  替代品，或者喜欢更简洁API的开发者。
```
pyclickhouse
```
：
- 特点：这是一个比较早期的ClickHouse Python客户端库。
- 劣势：
  - 目前看来，维护活跃度不高，可能存在一些未修复的bug或对ClickHouse新特性的支持不足。
  - 性能和功能可能不如
```
clickhouse-driver
```
    和
```
clickhouse-connect
```
    完善。
- 适用场景：除非有特殊历史项目依赖，否则不建议新项目使用。