chdb-datastore

chdb DataStore — 更快的 Pandas，仅此而已

核心要点

# Change this:
import pandas as pd
# To this:
import chdb.datastore as pd
# Everything else stays the same.

DataStore 是一个基于 ClickHouse 的惰性 pandas 替代品。现有的 pandas 代码无需改动即可使用，但操作会编译为优化后的 SQL，并且只会在需要结果时执行（例如调用 print()、len() 或进行迭代）。

pip install chdb

决策树：选择合适的方法

1. "I have a file/database and want to analyze it with pandas"
   → DataStore.from_file() / from_mysql() / from_s3() etc.
   → See references/connectors.md

2. "I need to join data from different sources"
   → Create DataStores from each source, use .join()
   → See examples/examples.md #3-5

3. "My pandas code is too slow"
   → import chdb.datastore as pd — change one line, keep the rest

4. "I need raw SQL queries"
   → Use the chdb-sql skill instead

连接任意数据源——统一模式

from datastore import DataStore

# Local file (auto-detects .parquet, .csv, .json, .arrow, .orc, .avro, .tsv, .xml)
ds = DataStore.from_file("sales.parquet")

# Database
ds = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")

# Cloud storage
ds = DataStore.from_s3("s3://bucket/data.parquet", nosign=True)

# URI shorthand — auto-detects source type
ds = DataStore.uri("mysql://root:pass@db:3306/shop/orders")

全部 16 种以上数据源和 URI 方案 → connectors.md

连接后——完整的 Pandas API

result = ds[ds["age"] > 25]                                          # filter
result = ds[["name", "city"]]                                        # select columns
result = ds.sort_values("revenue", ascending=False)                  # sort
result = ds.groupby("dept")["salary"].mean()                         # groupby
result = ds.assign(margin=lambda x: x["profit"] / x["revenue"])     # computed column
ds["name"].str.upper()                                               # string accessor
ds["date"].dt.year                                                   # datetime accessor
result = ds1.join(ds2, on="id")                                      # join
result = ds.head(10)                                                 # preview
print(ds.to_sql())                                                   # see generated SQL

支持 209 种 DataFrame 方法。完整 API → api-reference.md

跨数据源联接——杀手级功能

from datastore import DataStore

customers = DataStore.from_mysql(host="db:3306", database="crm", table="customers", user="root", password="pass")
orders = DataStore.from_file("orders.parquet")

result = (orders
    .join(customers, left_on="customer_id", right_on="id")
    .groupby("country")
    .agg({"amount": "sum", "rating": "mean"})
    .sort_values("sum", ascending=False))
print(result)

更多联接示例 → examples.md

写入数据

source = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")
target = DataStore("file", path="summary.parquet", format="Parquet")

target.insert_into("category", "total", "count").select_from(
    source.groupby("category").select("category", "sum(amount) AS total", "count() AS count")
).execute()

故障排除

问题	解决方法
ImportError: No module named 'chdb'	pip install chdb
ImportError: cannot import 'DataStore'	使用 from datastore import DataStore 或 from chdb.datastore import DataStore
数据库连接超时	在主机中包含端口：host="db:3306"，而不是 host="db"
联接返回空结果	检查键类型是否匹配（都为 int 或都为 string）；使用 .to_sql() 进行检查
结果异常	调用 ds.to_sql() 查看生成的 SQL 并进行调试
环境检查	运行 python scripts/verify_install.py（在技能目录中执行）

参考资料

• API 参考 — DataStore 方法签名完整列表
• 连接器 — 全部 16 种以上数据源的连接方法
• 示例 — 10 个以上可运行示例及预期输出
• 验证安装 — 环境验证脚本
• 官方文档

注意：本技能介绍如何使用 chdb DataStore。 如需执行原始 SQL 查询，请使用 chdb-sql 技能。 如需为 chdb 源代码做贡献，请参阅项目根目录中的 CLAUDE.md。