chdb-sql

chdb SQL — 嵌入Python的ClickHouse

直接在Python中运行ClickHouse SQL——无需服务器。查询本地文件、远程数据库和云存储，拥有完整的ClickHouse SQL能力。

pip install chdb

决策树：选择合适的API

1. 对文件或数据库的一次性查询 → chdb.query()
2. 多步骤分析（带表）         → Session
3. DB-API 2.0连接             → chdb.connect()
4. Pandas风格的DataFrame操作  → 改用chdb-datastore技能

chdb.query() — 一行代码，任意数据

import chdb

chdb.query("SELECT * FROM file('data.parquet', Parquet) WHERE price > 100 LIMIT 10")       # 本地文件
chdb.query("SELECT * FROM mysql('db:3306', 'shop', 'orders', 'root', 'pass')")              # 数据库
chdb.query("SELECT * FROM s3('s3://bucket/data.parquet', NOSIGN) LIMIT 10")                 # 云存储
chdb.query("SELECT * FROM deltaLake('s3://bucket/delta/table', NOSIGN) LIMIT 10")           # 数据湖

# 跨源JOIN
chdb.query("""
    SELECT u.name, o.amount FROM mysql('db:3306', 'crm', 'users', 'root', 'pass') AS u
    JOIN file('orders.parquet', Parquet) AS o ON u.id = o.user_id ORDER BY o.amount DESC
""")

data = {"name": ["Alice", "Bob"], "score": [95, 87]}
chdb.query("SELECT * FROM Python(data) ORDER BY score DESC")                                # Python数据
df = chdb.query("SELECT * FROM numbers(10)", "DataFrame")                                   # 输出格式
chdb.query("SELECT toDate({d:String}) + number FROM numbers({n:UInt64})",
    "DataFrame", params={"d": "2025-01-01", "n": 30})                                      # 参数化查询

表函数 → table-functions.md | SQL函数 → sql-functions.md | 完整API → api-reference.md

Session — 有状态分析管道

from chdb import session as chs
sess = chs.Session("./analytics_db")   # 持久化；Session()为内存模式

sess.query("CREATE TABLE users ENGINE=MergeTree() ORDER BY id AS SELECT * FROM mysql('db:3306','crm','users','root','pass')")
sess.query("CREATE TABLE events ENGINE=MergeTree() ORDER BY (ts,user_id) AS SELECT * FROM s3('s3://logs/events/*.parquet',NOSIGN)")
sess.query("""
    SELECT u.country, count() AS cnt, uniqExact(e.user_id) AS users
    FROM events e JOIN users u ON e.user_id = u.id
    WHERE e.ts >= today() - 7 GROUP BY u.country ORDER BY cnt DESC
""", "Pretty").show()
sess.close()

连接API（DB-API 2.0）

from chdb import dbapi
conn = dbapi.connect()
cur = conn.cursor()
cur.execute("SELECT * FROM file('data.parquet', Parquet) WHERE value > 100")
print(cur.fetchall())
cur.close()
conn.close()

故障排除

问题	解决方法
ImportError: No module named 'chdb'	pip install chdb
DB::Exception: FILE_NOT_FOUND	检查文件路径；使用绝对路径或确认当前工作目录
DB::Exception: Unknown table function	检查函数名拼写（例如deltaLake而非deltalake）
远程数据库连接被拒绝	检查host:port格式；确保远程数据库允许连接
环境检查	运行python scripts/verify_install.py（从技能目录）

参考

• API参考 — query/Session/connect签名
• 表函数 — 所有ClickHouse表函数
• SQL函数 — 常用SQL函数
• 示例 — 9个可运行示例及预期输出
• 官方文档

注意：本技能教授如何使用chdb SQL。
对于pandas风格的操作，请使用chdb-datastore技能。
如需为chdb源代码做贡献，请参见项目根目录下的CLAUDE.md。