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

DataStore 提供与 pandas 兼容且经过 SQL 优化的 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 采用 惰性求值 和 双引擎执行：

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

详见 执行模型。

​

从 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 参考文档