> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DataStore：支持 SQL 优化的与 pandas 兼容的 API

> 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 架构](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/chdb/datastore_architecture.png?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=39e13b7a77b0f28d676648b855d60db0)

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

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

详见[执行模型](https://clickhouse.com/docs/zh/chdb/datastore/execution-model.md)。

## 从 Pandas 一行代码迁移

```python theme={null}
# 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 在性能上有显著提升，尤其是在聚合和复杂管道方面：

| Operation | Pandas | DataStore | Speedup |
| - | - | - | - |
| GroupBy count | 347ms | 17ms | **19.93x** |
| 复杂管道 | 2,047ms | 380ms | **5.39x** |
| 过滤+排序+Head | 1,537ms | 350ms | **4.40x** |
| GroupBy 聚合 | 406ms | 141ms | **2.88x** |

*基于 1000 万行的基准测试。详见[基准测试脚本](https://github.com/chdb-io/chdb/blob/main/refs/benchmark_datastore_vs_pandas.py)和[性能指南](https://clickhouse.com/docs/zh/chdb/guides/pandas-performance.md)。*

## 何时使用 DataStore

**在以下情况下使用 DataStore：**

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

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

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

## 功能对比

| 功能 | Pandas | Polars | DuckDB | DataStore |
| - | - | - | - | - |
| 兼容 Pandas API | - | 部分 | 否 | **完全兼容** |
| 惰性求值 | 否 | 是 | 是 | **是** |
| 支持 SQL 查询 | 否 | 是 | 是 | **是** |
| ClickHouse 函数 | 否 | 否 | 否 | **是** |
| String/日期时间访问器 | 是 | 是 | 否 | **是 + 更多功能** |
| Array/JSON/URL/IP/Geo | 否 | 部分 | 否 | **是** |
| 直接查询文件 | 否 | 是 | 是 | **是** |
| 支持云存储 | 否 | 有限 | 是 | **是** |

## API 统计

| 类别 | 数量 | 覆盖率 |
| - | - | - |
| DataFrame 方法 | 209 | 100% 覆盖 pandas |
| Series.str 访问器 | 56 | 100% 覆盖 pandas |
| 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+** | - |

## 文档导航

### 开始使用

* [快速入门](https://clickhouse.com/docs/zh/chdb/datastore/quickstart.md) - 安装和基本使用
* [从 Pandas 迁移](https://clickhouse.com/docs/zh/chdb/guides/migration-from-pandas.md) - 迁移分步指南

### API 参考文档

* [工厂方法](https://clickhouse.com/docs/zh/chdb/datastore/factory-methods.md) - 从各种来源创建 DataStore
* [查询构建](https://clickhouse.com/docs/zh/chdb/datastore/query-building.md) - SQL 风格的查询操作
* [Pandas 兼容性](https://clickhouse.com/docs/zh/chdb/datastore/pandas-compat.md) - 全部 209 个与 pandas 兼容的方法
* [Accessors](https://clickhouse.com/docs/zh/chdb/datastore/accessors.md) - String、日期时间、Array、JSON、URL、IP、Geo 访问器
* [聚合](https://clickhouse.com/docs/zh/chdb/datastore/aggregation.md) - 聚合函数和窗口函数
* [I/O 操作](https://clickhouse.com/docs/zh/chdb/datastore/io.md) - 读取和写入数据

### 高级主题

* [执行模型](https://clickhouse.com/docs/zh/chdb/datastore/execution-model.md) - 惰性求值与缓存
* [类参考文档](https://clickhouse.com/docs/zh/chdb/datastore/class-reference.md) - 完整 API 参考文档

### 配置与调试

* [配置](https://clickhouse.com/docs/zh/chdb/configuration/index.md) - 所有配置选项
* [性能模式](https://clickhouse.com/docs/zh/chdb/configuration/performance-mode.md) - 以 SQL 为先、实现最大吞吐量
* [调试](https://clickhouse.com/docs/zh/chdb/debugging/index.md) - Explain、性能分析和日志

### Pandas 用户指南

* [Pandas Cookbook](https://clickhouse.com/docs/zh/chdb/guides/pandas-cookbook.md) - 常见用法
* [关键区别](https://clickhouse.com/docs/zh/chdb/guides/pandas-differences.md) - 与 pandas 的重要区别
* [性能指南](https://clickhouse.com/docs/zh/chdb/guides/pandas-performance.md) - 优化技巧
* [面向 Pandas 用户的 SQL](https://clickhouse.com/docs/zh/chdb/guides/pandas-to-sql.md) - 理解 pandas 操作背后的 SQL

## 快速示例

```python theme={null}
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？** 从[快速入门指南](https://clickhouse.com/docs/zh/chdb/datastore/quickstart.md)开始
* **正在从 pandas 迁移？** 阅读[迁移指南](https://clickhouse.com/docs/zh/chdb/guides/migration-from-pandas.md)
* **想进一步了解？** 查看 [API 参考文档](https://clickhouse.com/docs/zh/chdb/datastore/class-reference.md)