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 采用 惰性求值 和 双引擎执行：

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

详见执行模型。

# Before (pandas)
import pandas as pd

df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# After (DataStore) - just change the import!
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 在性能上有显著提升，尤其是在聚合和复杂管道方面：

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

在以下情况下使用 DataStore：

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

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

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

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

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

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

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

• Pandas Cookbook - 常见用法
• 关键区别 - 与 pandas 的重要区别
• 性能指南 - 优化技巧
• 面向 Pandas 用户的 SQL - 理解 pandas 操作背后的 SQL

from chdb import datastore as pd

# Read data from various sources
ds = pd.read_csv("sales.csv")
# or: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# or: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# Familiar pandas operations - automatically optimized to 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
)

# View the generated SQL
print(result.to_sql())

# Execute and get results
df = result.to_df()  # Returns pandas DataFrame

• 刚开始使用 DataStore？ 从快速入门指南开始
• 正在从 pandas 迁移？ 阅读迁移指南
• 想进一步了解？ 查看 API 参考文档