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

# 性能模式 (compat_mode)

> SQL 优先的性能模式，禁用 Pandas 兼容性带来的额外开销，以实现最大吞吐量

DataStore 提供两种兼容模式，用于控制输出是为 Pandas 兼容性调整，还是针对原生 SQL 性能进行优化。

<div id="overview">
  ## 概述
</div>

| 模式              | `compat_mode` 值 | 描述                                                                                        |
| --------------- | --------------- | ----------------------------------------------------------------------------------------- |
| **Pandas** (默认) | `"pandas"`      | 完全兼容 pandas 的行为。保留行顺序，支持 MultiIndex、set\_index、dtype 修正、稳定排序的平局裁定规则，以及 `-If`/`isNaN` 包装器。 |
| **Performance** | `"performance"` | 采用 SQL 优先的执行方式。移除所有 pandas 兼容性开销。吞吐量最高，但结果在结构上可能与 pandas 不同。                              |

<div id="what-it-disables">
  ### 性能模式 会禁用哪些功能
</div>

| 开销                              | Pandas 模式行为                                                    | 性能模式 行为                                       |
| ------------------------------- | -------------------------------------------------------------- | --------------------------------------------- |
| **保留行顺序**                       | 注入 `_row_id`、`rowNumberInAllBlocks()` 和 `__orig_row_num__` 子查询 | 已禁用 — 不保证行顺序                                  |
| **稳定排序的平局决胜项**                  | 在 ORDER BY 后附加 `rowNumberInAllBlocks() ASC`                    | 已禁用 — 相同值的顺序可能是任意的                            |
| **Parquet preserve\_order**     | `input_format_parquet_preserve_order=1`                        | 已禁用 — 允许并行读取 Parquet                          |
| **GroupBy 自动 ORDER BY**         | 添加 `ORDER BY group_key` (pandas 默认 `sort=True`)                | 已禁用 — 返回的分组顺序可能是任意的                           |
| **GroupBy dropna WHERE**        | 添加 `WHERE key IS NOT NULL` (pandas 默认 `dropna=True`)           | 已禁用 — 包含 NULL 分组                              |
| **GroupBy set\_index**          | 将分组键设为索引                                                       | 已禁用 — 分组键保留为列                                 |
| **MultiIndex 列**                | `agg({'col': ['sum','mean']})` 返回 MultiIndex 列                 | 已禁用 — 改为扁平列名 (`col_sum`、`col_mean`)           |
| **`-If`/`isNaN` 包装**            | 为 `skipna` 使用 `sumIf(col, NOT isNaN(col))`                     | 已禁用 — 使用普通 `sum(col)` (ClickHouse 原生会跳过 NULL) |
| **对 count 使用 `toInt64`**        | 使用 `toInt64(count())` 以匹配 pandas 的 int64                       | 已禁用 — 返回原生 SQL dtype                          |
| **对全 NaN 的 sum 使用 `fillna(0)`** | 全为 NaN 的 sum 返回 0 (pandas 行为)                                  | 已禁用 — 返回 NULL                                 |
| **Dtype 修正**                    | 如 `abs()` 从无符号转为有符号等                                           | 已禁用 — 使用原生 SQL dtype                          |
| **索引保留**                        | SQL 执行后恢复原始索引                                                  | 已禁用                                           |
| **`first()`/`last()`**          | `argMin/argMax(col, rowNumberInAllBlocks())`                   | `any(col)` / `anyLast(col)` — 更快，但非确定性        |
| **单 SQL 聚合**                    | ColumnExpr groupby 会物化中间 DataFrame                             | 将 `LazyGroupByAgg` 注入惰性操作链中 — 单条 SQL 查询       |

***

<div id="enabling">
  ## 启用性能模式
</div>

<div id="using-config">
  ### 使用 config 对象
</div>

```python theme={null}
from chdb.datastore.config import config

# 启用性能模式
config.use_performance_mode()

# 切换回 pandas 兼容模式
config.use_pandas_compat()

# 查看当前模式
print(config.compat_mode)  # 'pandas' or 'performance'
```

<div id="using-functions">
  ### 使用模块级函数
</div>

```python theme={null}
from chdb.datastore.config import set_compat_mode, CompatMode, is_performance_mode

# 启用性能模式
set_compat_mode(CompatMode.PERFORMANCE)

# 检查
print(is_performance_mode())  # True

# 恢复默认
set_compat_mode(CompatMode.PANDAS)
```

<div id="using-imports">
  ### 使用简化导入
</div>

```python theme={null}
from chdb import use_performance_mode, use_pandas_compat

use_performance_mode()
# ... 高性能操作 ...
use_pandas_compat()
```

<Note>
  启用性能模式后，执行引擎会自动设为 `chdb`。无需另外调用 `config.use_chdb()`。
</Note>

***

<div id="when-to-use">
  ## 何时使用性能模式
</div>

**在以下情况下使用性能模式：**

* 处理大型数据集 (数十万到数百万行)
* 运行以聚合为主的工作负载 (groupby、sum、mean、count)
* 行顺序不重要 (例如聚合结果、报表、仪表盘)
* 你希望获得最高的 SQL 吞吐量和最低的开销
* 需要关注内存使用量 (并行读取 Parquet，无中间 DataFrame)

**在以下情况下请保持使用 pandas 模式：**

* 你需要完全一致的 pandas 行为 (行顺序、MultiIndex、dtypes)
* 你依赖 `first()`/`last()` 返回真正的第一行/最后一行
* 你使用依赖行顺序的 `shift()`、`diff()`、`cumsum()`
* 你正在编写测试，将 DataStore 的输出与 pandas 进行比较

***

<div id="behavior-differences">
  ## 行为差异
</div>

<div id="row-order">
  ### 行顺序
</div>

在性能模式下，任何操作的行顺序都**无法保证**。这包括：

* 过滤结果
* GroupBy 聚合结果
* 未显式使用 `sort_values()` 的 `head()` / `tail()`
* `first()` / `last()` 聚合

如果你需要有序结果，请显式添加 `sort_values()`：

```python theme={null}
config.use_performance_mode()

ds = pd.read_csv("data.csv")

# 无序（快速）
result = ds.groupby("region")["revenue"].sum()

# 有序（仍然快速，只是添加了 ORDER BY）
result = ds.groupby("region")["revenue"].sum().sort_values()
```

<div id="groupby-results">
  ### GroupBy 结果
</div>

| 方面                 | Pandas 模式             | 性能模式                       |
| ------------------ | --------------------- | -------------------------- |
| 分组键位置              | 索引 (通过 `set_index`)   | 普通列                        |
| 分组顺序               | 按键排序 (默认)             | 任意顺序                       |
| NULL 分组            | 排除 (默认 `dropna=True`) | 包含                         |
| 列格式                | 多重聚合时使用 MultiIndex    | 扁平命名 (`col_func`)          |
| `first()`/`last()` | 确定性 (按行顺序)            | 非确定性 (`any()`/`anyLast()`) |

<div id="aggregation">
  ### 聚合
</div>

```python theme={null}
config.use_performance_mode()

# 全为 NaN 的分组求和返回 NULL（而非 0）
# Count 返回原生 uint64（而非强制转换为 int64）
# 无需 -If 包装器：使用 sum() 而非 sumIf()
result = ds.groupby("cat")["val"].sum()
```

<div id="single-sql">
  ### 单条 SQL 执行
</div>

在性能模式下，`ColumnExpr` 的 groupby 聚合 (例如 `ds[condition].groupby('col')['val'].sum()`) 会以**单条 SQL 查询**执行，而不是像 pandas 模式那样分两步进行：

```python theme={null}
config.use_performance_mode()

# Pandas 模式：两个 SQL 查询（过滤器 → 物化 → groupby）
# 性能模式：一个 SQL 查询（WHERE + GROUP BY 合并为单个查询）
result = ds[ds["rating"] > 3.5].groupby("category")["revenue"].sum()

# 生成的 SQL（单个查询）：
# SELECT category, sum(revenue) FROM data WHERE rating > 3.5 GROUP BY category
```

这避免了中间 DataFrame 的物化过程，并且可以显著降低内存占用并缩短执行时间。

***

<div id="vs-execution-engine">
  ## 与执行引擎的比较
</div>

性能模式 (`compat_mode`) 和执行引擎 (`execution_engine`) 是**两个相互独立的配置维度**：

| 配置项                | 控制内容                        | 取值                       |
| ------------------ | --------------------------- | ------------------------ |
| `execution_engine` | **由哪个引擎**执行计算               | `auto`, `chdb`, `pandas` |
| `compat_mode`      | **是否**为实现 Pandas 兼容性而调整输出形态 | `pandas`, `performance`  |

将 `compat_mode='performance'` 设为性能模式时，`execution_engine` 会自动设为 `chdb`，因为性能模式是为 SQL 执行而设计的。

```python theme={null}
from chdb.datastore.config import config

# 这两项配置相互独立
config.use_chdb()              # 强制使用 chDB 引擎，保留 pandas 兼容性
config.use_performance_mode()  # 强制使用 chDB + 去除 pandas 开销
```

***

<div id="testing">
  ## 使用性能模式测试
</div>

为性能模式编写测试时，结果的行顺序和结构格式可能与 pandas 不一致。请采用以下策略：

<div id="sort-then-compare">
  ### 先排序再比较 (聚合、过滤器)
</div>

```python theme={null}
# 比较前先对两侧按相同列排序
ds_result = ds.groupby("cat")["val"].sum()
pd_result = pd_df.groupby("cat")["val"].sum()

ds_sorted = ds_result.sort_index()
pd_sorted = pd_result.sort_index()
np.testing.assert_array_equal(ds_sorted.values, pd_sorted.values)
```

<div id="value-range-check">
  ### 取值范围检查 (首/尾)
</div>

```python theme={null}
# first() 与 any() 结合使用，从分组中返回任意一个元素
result = ds.groupby("cat")["val"].first()
for group_key in groups:
    assert result.loc[group_key] in group_values[group_key]
```

<div id="schema-and-count">
  ### Schema 与计数 (LIMIT 不使用 ORDER BY)
</div>

```python theme={null}
# head() 不带 sort_values：行集合是非确定性的
result = ds.head(5)
assert len(result) == 5
assert set(result.columns) == expected_columns
```

***

<div id="best-practices">
  ## 最佳实践
</div>

<div id="enable-early">
  ### 1. 尽早在脚本中启用
</div>

```python theme={null}
from chdb.datastore.config import config

config.use_performance_mode()

# 所有后续操作均可受益
ds = pd.read_parquet("data.parquet")
result = ds[ds["amount"] > 100].groupby("region")["amount"].sum()
```

<div id="explicit-sort">
  ### 2. 当顺序很重要时，显式指定排序
</div>

```python theme={null}
# 用于需要有序输出的展示或下游处理
result = (ds
    .groupby("region")["revenue"].sum()
    .sort_values(ascending=False)
)
```

<div id="batch-etl">
  ### 3. 用于批处理/ETL 类工作负载
</div>

```python theme={null}
config.use_performance_mode()

# ETL 管道 — 顺序无关紧要，吞吐量才是关键
summary = (ds
    .filter(ds["date"] >= "2024-01-01")
    .groupby(["region", "product"])
    .agg({"revenue": "sum", "quantity": "sum", "rating": "mean"})
)
summary.to_df().to_parquet("summary.parquet")
```

<div id="switch-modes">
  ### 4. 在同一会话中切换模式
</div>

```python theme={null}
# 高性能模式，适用于大量计算
config.use_performance_mode()
aggregated = ds.groupby("cat")["val"].sum()

# 切换回 pandas 模式以进行精确匹配比较
config.use_pandas_compat()
detailed = ds[ds["val"] > 100].head(10)
```

***

<div id="related">
  ## 相关文档
</div>

* [执行引擎](/zh/products/chdb/configuration/execution-engine) — 引擎选择 (auto/chdb/pandas)
* [性能指南](/zh/products/chdb/guides/pandas-performance) — 通用优化建议
* [与 pandas 的主要差异](/zh/products/chdb/guides/pandas-differences) — 行为差异