DataStore：经过 SQL 优化的与 Pandas 兼容的 API

DataStore 是 chDB 提供的与 pandas 兼容的 API，它将熟悉的 pandas DataFrame 接口与 SQL 查询优化能力结合在一起，让您能够编写 pandas 风格的代码，同时享有 ClickHouse 的性能。

主要特性

Pandas 兼容性：209 个 pandas DataFrame 方法、56 个 .str 方法、42+ 个 .dt 方法
SQL 优化：操作会自动编译为优化后的 SQL 查询
惰性求值：操作会延迟到需要结果时才执行
630+ 个 API 方法：提供全面的数据操作 API
ClickHouse 扩展：提供 pandas 中没有的额外访问器 (.arr、.json、.url、.ip、.geo)

架构

DataStore 采用 惰性求值 和 双引擎执行：

惰性操作链：操作会被记录下来，而不是立即执行
智能引擎选择：QueryPlanner 会将各个阶段分发到最合适的引擎 (SQL 使用 chDB，复杂操作使用 Pandas)
中间结果缓存：每一步的结果都会被缓存，以便快速进行迭代探索

详见执行模型。

从 Pandas 进行一行代码迁移

# 之前（pandas）
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# 之后（DataStore）- 只需更改导入语句！
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

您现有的 pandas 代码无需任何修改即可照常运行，只是现在改由 ClickHouse 引擎执行。

性能对比

与 pandas 相比，DataStore 的性能有显著提升，尤其是在聚合和复杂管道方面：

Operation	Pandas	DataStore	Speedup
GroupBy count	347ms	17ms	19.93x
Complex pipeline	2,047ms	380ms	5.39x
Filter+Sort+Head	1,537ms	350ms	4.40x
GroupBy agg	406ms	141ms	2.88x

基于 1000 万行的基准测试。详见基准测试脚本和性能指南。

何时使用 DataStore

在以下情况下使用 DataStore：

处理大型数据集 (数百万行)
执行聚合和 groupby 操作
从文件、数据库或云存储查询数据
构建复杂的数据管道
你希望获得 pandas API 的易用性和更好的性能

在以下情况下使用原生 SQL API：

你更喜欢直接编写 SQL
你需要对查询执行进行细粒度控制
需要使用 pandas API 未提供的 ClickHouse 特性

特性对比

特性	Pandas	Polars	DuckDB	DataStore
兼容 Pandas API	-	部分	否	完整兼容
惰性求值	否	是	是	是
支持 SQL 查询	否	是	是	是
ClickHouse 函数	否	否	否	是
String/DateTime 访问器	是	是	否	是 + 额外功能
Array/JSON/URL/IP/Geo	否	部分	否	是
直接查询文件	否	是	是	是
支持云存储	否	有限	是	是

API 统计信息

类别	数量	覆盖率
DataFrame 方法	209	覆盖 pandas 的 100%
Series.str 访问器	56	覆盖 pandas 的 100%
Series.dt 访问器	42+	100%+ (包括 ClickHouse 扩展)
Series.arr 访问器	37	ClickHouse 特有
Series.json 访问器	13	ClickHouse 特有
Series.url 访问器	15	ClickHouse 特有
Series.ip 访问器	9	ClickHouse 特有
Series.geo 访问器	14	ClickHouse 特有
API 方法总计	630+	-

开始使用

快速入门 - 安装和基本用法
从 Pandas 迁移 - 分步迁移指南

API 参考文档

工厂方法 - 从各种来源创建 DataStore
查询构建 - SQL 风格的查询操作
Pandas 兼容性 - 全部 209 个兼容 pandas 的方法
访问器 - String、DateTime、Array、JSON、URL、IP、Geo 访问器
聚合 - 聚合函数和窗口函数
I/O 操作 - 读写数据

高级主题

执行模型 - 惰性求值与缓存
类参考文档 - 完整 API 参考文档

配置与调试

配置 - 所有配置选项
性能模式 - 以 SQL 为核心、实现最大吞吐量的模式
调试 - Explain、性能分析和日志

Pandas 用户指南

Pandas Cookbook - 常见用法
Key Differences - 与 pandas 的主要区别
性能指南 - 优化技巧
SQL for Pandas Users - 了解 pandas 操作背后的 SQL

快速示例

from chdb import datastore as pd

# 从各种来源读取数据
ds = pd.read_csv("sales.csv")
# 或：ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# 或：ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# 熟悉的 pandas 操作 - 自动优化为 SQL
result = (ds
    .filter(ds['amount'] > 1000)           # WHERE amount > 1000
    .groupby('region')                      # GROUP BY region
    .agg({'amount': ['sum', 'mean']})       # SUM(amount), AVG(amount)
    .sort_values('sum', ascending=False)    # ORDER BY sum DESC
    .head(10)                               # LIMIT 10
)

# 查看生成的 SQL
print(result.to_sql())

# 执行并获取结果
df = result.to_df()  # 返回 pandas DataFrame

后续步骤

刚接触 DataStore？ 从快速入门指南开始
从 pandas 迁移过来？ 阅读迁移指南
想了解更多？ 请参阅 API 参考文档

​主要特性

​架构

​从 Pandas 进行一行代码迁移

​性能对比

​何时使用 DataStore

​特性对比

​API 统计信息

​文档导航

​开始使用

​API 参考文档

​高级主题

​配置与调试

​Pandas 用户指南

​快速示例

​后续步骤