> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> DataStore 提供与 pandas 兼容且经过 SQL 优化的 API，可用于高性能数据分析

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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

<div id="key-features">
  ## 主要特性
</div>

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

<div id="architecture">
  ## 架构
</div>

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/Sr_JUhB6DLeeNQJ0/images/chdb/datastore_architecture.png?fit=max&auto=format&n=Sr_JUhB6DLeeNQJ0&q=85&s=0726168ff23fdb2e7e615ad58d79a4fa" alt="DataStore 架构" width="2816" height="1536" data-path="images/chdb/datastore_architecture.png" />

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

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

详见 [执行模型](/zh/products/chdb/datastore/execution-model)。

<div id="migration">
  ## 从 Pandas 进行一行代码迁移
</div>

```python theme={null}
# 之前（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 引擎执行。

<div id="performance">
  ## 性能对比
</div>

与 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 万行的基准测试。详见[基准测试脚本](https://github.com/chdb-io/chdb/blob/main/refs/benchmark_datastore_vs_pandas.py)和[性能指南](/zh/products/chdb/guides/pandas-performance)。*

<div id="when-to-use">
  ## 何时使用 DataStore
</div>

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

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

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

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

<div id="comparison">
  ## 特性对比
</div>

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

<div id="api-stats">
  ## API 统计信息
</div>

| 类别              | 数量       | 覆盖率                      |
| --------------- | -------- | ------------------------ |
| 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+** | -                        |

<div id="navigation">
  ## 文档导航
</div>

<div id="getting-started">
  ### 开始使用
</div>

* [快速入门](/zh/products/chdb/datastore/quickstart) - 安装和基本用法
* [从 Pandas 迁移](/zh/products/chdb/guides/migration-from-pandas) - 分步迁移指南

<div id="api-reference">
  ### API 参考文档
</div>

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

<div id="advanced-topics">
  ### 高级主题
</div>

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

<div id="configuration-debugging">
  ### 配置与调试
</div>

* [配置](/zh/products/chdb/configuration/index) - 所有配置选项
* [性能模式](/zh/products/chdb/configuration/performance-mode) - 以 SQL 为核心、实现最大吞吐量的模式
* [调试](/zh/products/chdb/debugging/index) - Explain、性能分析和日志

<div id="pandas-user-guides">
  ### Pandas 用户指南
</div>

* [Pandas Cookbook](/zh/products/chdb/guides/pandas-cookbook) - 常见用法
* [Key Differences](/zh/products/chdb/guides/pandas-differences) - 与 pandas 的主要区别
* [性能指南](/zh/products/chdb/guides/pandas-performance) - 优化技巧
* [SQL for Pandas Users](/zh/products/chdb/guides/pandas-to-sql) - 了解 pandas 操作背后的 SQL

<div id="quick-example">
  ## 快速示例
</div>

```python theme={null}
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
```

<div id="next-steps">
  ## 后续步骤
</div>

* **刚接触 DataStore？** 从[快速入门指南](/zh/products/chdb/datastore/quickstart)开始
* **从 pandas 迁移过来？** 阅读[迁移指南](/zh/products/chdb/guides/migration-from-pandas)
* **想了解更多？** 请参阅 [API 参考文档](/zh/products/chdb/datastore/class-reference)