interactive-tpch-benchmark

用途

Interactive Analytics TPC-H Benchmark 是一个本地基准测试工具，用于在 Snowflake 上搭建并运行 TPC-H 基准，对比 Interactive Warehouses 与 Standard Warehouses 的执行表现。它面向需要评估两类仓库在 TPC-H 工作负载下差异的用户，仅在用户明确提及 TPC-H 时使用。

前置条件

已安装 uv（Python 包运行器）。
已在 ~/.snowflake/connections.toml 中配置 Snowflake 连接。
拥有可创建数据库和仓库权限的角色（例如 SYSADMIN 或 ACCOUNTADMIN）。

主要能力

Setup：从 SNOWFLAKE_SAMPLE_DATA 复制 TPC-H 数据到本地基准数据库，创建标准表与交互式表，并创建对应的标准仓库与交互式仓库。
Run benchmark：执行 22 条 TPC-H 查询并收集计时结果，支持选择仓库类型、表类型、规模、工作负载、指定查询、重复次数等。
Teardown：删除指定规模的基准资源，默认删除仓库以及标准、交互式、iceberg 表模式，数据库默认保留。

使用方式

工作流

检测意图：询问用户要执行 Setup、Run benchmark 还是 Teardown，并路由到对应部分。
Setup：
- 确保 tpc-h/ 下存在 .env：cp tpc-h/.env.example tpc-h/.env
- 询问配置：CONNECTION_NAME（Snowflake 连接名）、SOLUTION_NAME（对象名前缀，默认 TPCH）、DEFAULT_SCALE（规模因子：1、10、100 或 1000，默认 10）。
- 更新 tpc-h/.env。
- 运行：cd <REPO_ROOT>/tpc-h && ./iwtpch.sh setup --scale <SCALE>
- 创建的对象：数据库 <SOLUTION_NAME>_BENCH_DB；模式 TPCH_SF<scale>（标准表）、TPCH_SF<scale>_IT（交互式表）；仓库 <SOLUTION_NAME>_BENCH_WH_STD_<scale>（标准）、<SOLUTION_NAME>_BENCH_WH_INT_<scale>（交互式）。交互式仓库会附加到 _IT 模式下的全部 8 张交互式表。每个规模因子需单独运行 setup。
Run benchmark：
- 询问：仓库类型（interactive 默认，或 standard）、表类型（standard 默认、interactive 或 iceberg，iceberg 仅在已设置时可用）、规模（1、10、100、1000）、工作负载（original 标准 SQL 或 modern 窗口函数、QUALIFY）、指定查询（可选，逗号分隔如 2,11,15）、每查询重复次数（默认 3，保留最佳时间）。
- 运行：cd <REPO_ROOT>/tpc-h && ./iwtpch.sh run --warehouse-type <WAREHOUSE_TYPE> --tables-type <TABLES_TYPE> --scale <SCALE> --workload <WORKLOAD>
- 可选标志：--queries 2,11,15 仅运行指定查询；--avg 报告重复的平均值（一次预热后）而非最佳值；--repeats 5 每查询 N 次取最佳；--iterations 3 完整工作负载轮次。
- 结果保存到 tpc-h/results/run_<warehouse_type>-<tables_type>_sf<scale>_<workload>_<timestamp>.json 和 .csv。
- 典型对比流程：
```
./iwtpch.sh run --warehouse-type interactive --tables-type interactive --scale 10 --workload original
./iwtpch.sh run --warehouse-type standard --tables-type standard --scale 10 --workload original
```
- 在 SF1 时，结果验证会自动对照 tpc-h-results-1GB.json 中的参考值检查。
Teardown：
- 运行：cd <REPO_ROOT>/tpc-h && ./iwtpch.sh teardown --scale <SCALE>
- 默认删除该规模的仓库以及标准、交互式、iceberg 表模式；数据库保留，除非传入 --drop-database。
- 若要少删，可传 --tables-type <standard|interactive|iceberg> 和/或 --warehouse-type <standard|interactive>。

停止点

检测意图后：确认操作再继续。
收集配置值后：确认 .env 内容再运行 setup。
Teardown 前：确认要删除的资源。

适用场景

需要在本地对比 Snowflake Interactive Warehouses 与 Standard Warehouses 在 TPC-H 工作负载下的性能。
需要按不同规模因子（1、10、100、1000）运行 TPC-H 查询并收集计时结果。
需要验证 SF1 结果是否符合参考值。

限制

仅在用户明确提及 TPC-H 时使用。
需要 uv、Snowflake 连接配置以及具备创建数据库和仓库权限的角色。
iceberg 表类型仅在已设置时可用。
每个规模因子需单独运行 setup。
其他功能、收费、价格、平台或效果信息暂未提供。

故障排除

uv: command not found：安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
SNOWFLAKE_SAMPLE_DATA not accessible：确保角色对共享数据库有 USAGE 权限。
连接错误：验证连接名存在于 ~/.snowflake/connections.toml。

输出

TPC-H 基准结果（JSON + CSV）位于 tpc-h/results/。