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

# TPC-DS 套件（数据仓库）

> 通过基准套件契约，在 duckdb-local 参考平台上运行 TPC-DS。

TPC-DS 是 Clousight Bench 的第二个基准套件，也是 `data-warehouse`（数据仓库）
域上的第一个——`benchmark_suite` / `evaluator` 契约由此从 agent 套件（SWE-bench）
泛化到了 OLAP/数据领域。首个平台是 `duckdb-local`：一个无云、单机的**参考**引擎
（相当于 agent-runtime 的 `local-sim`），完全离线运行。

## 运行（无需云账号）

```bash theme={null}
# 离线 mock 路径——无需 DuckDB，跑通整条阶段机：
printf 'target:\n  mode: mock\n' > mock.yaml
csbench run --domain data-warehouse --benchmark tpc-ds \
  --platform duckdb-local --config mock.yaml

# 真实 DuckDB SF1 运行（需要 [tpcds] extra：pip install clousight-bench[tpcds]）：
printf 'target:\n  mode: runtime\nparams:\n  scale_factor: 1\n  query_ids: [3, 7, 42]\n' > real.yaml
csbench run --domain data-warehouse --benchmark tpc-ds \
  --platform duckdb-local --config real.yaml
```

`params.scale_factor` 默认 `1`；`params.query_ids` 默认全部 99 条。省略
`query_ids` 即跑全集（SF1 下约 1.3s，另有一次性约 6s 的数据生成）。

## 测量什么

`official-tpcds-evaluator` 产出三个 `tpc-ds.*` 测量：

| 测量 | 含义 | reproducibility\_class |
| - | - | - |
| `tpc-ds.queries_passed` | 结果与按 SF 键控的固化参考一致的查询占比（`sf<sf>_digests.json`；仅随包提供 SF1——其他 SF 下省略） | `deterministic` |
| `tpc-ds.geomean_latency_ms` | 每查询墙钟时间的几何均值 | `environmental` |
| `tpc-ds.total_runtime_ms` | 每查询墙钟时间之和 | `environmental` |

三者都带 `official=True`——在本框架里这是**溯源**标志（"由套件的官方评估器产出"），
并非审计声明；数字是否漂移由 `reproducibility_class` 承载。

## 正确性：固化的 SF1 参考

DuckDB 的 `tpcds_answers()` 不可用（无参、默认 SF10），因此正确性用**固化 SF1 参考**
比对：每条查询归一化后的结果摘要，对照一次性固化（钉住 DuckDB + 扩展版本）的参考
（`suites/tpc_ds/fixtures/reference/sf1_digests.json`，由
`scripts/capture_tpcds_reference.py` 生成）。这是针对一个公认实现的确定性
复现/回归校验——**不是经外部审计的 TPC 答案**——且**仅在 scale factor 1** 时产出
（参考只有 SF1）。摘要归一化对数值定精度、对行排序，跨平台稳定；真实运行会在 CI 里
复现固化的参考。

## 本切片的刻意边界

* 正确性仅限 SF1；更高 scale factor 只报性能。
* *审计级* **QphDS** 数从不声称。unaudited 的官方公式复合分是存在的：
  `params.mode: official` 运行完整序列（load + power + 并发 throughput 流 +
  data maintenance + ACID 门）并计算 QphDS\@SF——见下文的**官方模式**一节。
* 大数据规模与分布式引擎（EMR 上的 Spark、云数仓）属后续阶段，作为同一套件下的
  更多 `data-warehouse` 平台加入。

## 姊妹套件：TPC-H

TPC-H 是同一 `data-warehouse` 域、同一 `duckdb-local` 平台上的第二个 OLAP 套件
——证明新套件能低成本挂上契约。它与 TPC-DS 形态相同（离线 mock + 真实 DuckDB、
老实的每查询延迟），只是改用 DuckDB 的 `tpch` 扩展（`dbgen` + 22 条查询经
`PRAGMA tpch(n)`）——并在正确性与复合分上走得更远：SF 1 / 0.1 / 0.01 三档按 SF
键控的**已验证**参考（每档都在捕获时逐单元格对照 DuckDB 官方 `tpch_answers()`
验证过），以及自己的官方公式 QphH\@Size 模式。见 [TPC-H 套件](/docs/tpch-suite)。

```bash theme={null}
csbench run --domain data-warehouse --benchmark tpc-h \
  --platform duckdb-local --config mock.yaml   # 或 mode: runtime 的 real.yaml
```

测量为 `tpc-h.queries_passed` / `tpc-h.geomean_latency_ms` /
`tpc-h.total_runtime_ms`。真实路径需 `[tpch]` extra。与 TPC-DS 不同，DuckDB 自带
可用的 `tpch_answers()` 官方答案，因此 TPC-H 的正确性是**已验证**的，而不只是固化：
`scripts/capture_tpch_reference.py` 在捕获时逐条对照官方答案验证每个参考条目并盖上
`verified_official` 戳——随包提供的三个 scale factor（1、0.1、0.01）各 22/22 全部
验证通过。

## 官方模式（QphDS\@SF）

`params.mode: official` 运行 TPC-DS 官方序列——Load → Power(99 查询单流)→
Throughput Test 1 → Data Maintenance 1 → Throughput Test 2 → Data Maintenance 2 →
ACID 门——由 `official-tpcds-qphds-evaluator` 计算官方复合分:

```
QphDS@SF = ⌊ SF · Q / ⁴√(T_PT · T_TT · T_DM · T_LD) ⌋
```

```bash theme={null}
printf 'target:\n  mode: runtime\nparams:\n  mode: official\n  scale_factor: 1\n  evaluator: official-tpcds-qphds-evaluator\n' > ds-official.yaml
csbench run --domain data-warehouse --benchmark tpc-ds --platform duckdb-local --config ds-official.yaml
```

`official-tpcds-qphds-evaluator` 产出:

| 测量 | 含义 | reproducibility\_class |
| - | - | - |
| `tpc-ds.qphds_at_size` | QphDS\@SF 复合分(unaudited 声明在其 `notes` 里) | `environmental` |
| `tpc-ds.load_time_s` | Load Test 墙钟 | `environmental` |
| `tpc-ds.power_test_s` | Power Test——每查询区间之和 | `environmental` |
| `tpc-ds.throughput_test_s` | Throughput Test 1 + 2 合计 | `environmental` |
| `tpc-ds.maintenance_test_s` | Data Maintenance 1 + 2 合计 | `environmental` |
| `tpc-ds.acid_atomicity`, `tpc-ds.acid_isolation` | ACID 探针通过/失败(一致性与持久性为 `n/a`——省略) | `deterministic` |
| `tpc-ds.queries_passed` | 仅 SF1——Power 流上的固化参考正确性 | `deterministic` |

`params.streams` 默认取官方最小值(4)。运行同时产出 OTel 原生 trace
(`trajectory.jsonl`)——viewer waterfall 展示 Power 查询、两轮吞吐测试的并发流泳道
与 DM 窗口。

<Note>
  **Unaudited,替代项如实声明**:DuckDB 的 `tpcds` 扩展没有 LF\_\* 维护函数,数据维护
  为 clousight 生成的 `store_sales` 插入+删除往返;未内置官方排列表,查询排序始终是
  确定性的 clousight `generated` 排序(记入 `ordering_source` 并折入 dataset digest);
  ACID 通用探针只测原子性/隔离性——一致性与持久性为 `n/a`。每个复合分的 `notes` 都带
  这些声明。
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.