SQL 运行数据收集：基线数据生成最终方案

分支文档快照 · 同步于 2026-09-09 · 来源：origin/summer-intern @ 9f4cdc5 · 原路径：docs/data/02-SQL基线数据生成最终方案.md。正文描述的是该分支的方案或进展，合入与验收状态以当前看板为准。

1. 目标与适用范围

本方案用于固定测试环境、单批次 50 条以内 SQL 的标准化基线生成。基线不是某一次执行耗时，而是同一 SQL、参数集、数据快照和环境下多次运行形成的稳定参考。

默认执行协议：

1 次预热 + 5 次正式执行
以正式执行耗时中位数作为 baseline_time
如正式执行不计算完整结果哈希，再增加 1 次 validation 校验

建议 Excel 使用以下 Sheet：

1. 03_环境台账
2. 04_运行明细
3. 05_基线汇总

以上 Sheet 与数据清洗方案中的 01_SQL台账、02_参数集 共同组成第一阶段工作簿。

2. 基线前置条件

同一基线版本必须固定：

• case_id
• parameter_set_id
• environment_id
• data_snapshot
• 数据库版本和实例规格
• 数据库配置与会话配置
• 索引状态
• 缓存策略
• 执行方式和超时配置

以下任一条件发生变化时，创建新的 environment_id 或 baseline_version，不得覆盖旧基线：

• 数据库版本或实例规格变化。
• 数据快照发生明显变化。
• 索引结构变化。
• 优化器或关键数据库参数变化。
• 集中式/分布式部署方式变化。

3. 标准执行流程

3.1 预检

执行语法检查或 EXPLAIN，确认：

• SQL、表和字段存在。
• 参数有效。
• SQL 可在测试环境安全执行。
• 预计耗时没有超过测试窗口。

预检失败时不生成有效基线，baseline_status 标记为 blocked，并记录阻塞原因。

3.2 预热

使用完全相同的 SQL 和参数执行一次：

• sql_version = original
• run_stage = baseline
• run_type = warmup
• included_in_metrics = no

预热记录仍写入运行明细，但不参与中位数和波动率计算。

3.3 正式执行

连续执行五次，每次生成独立 run_id：

RUN_CAMS_0001_P01_B01_01
RUN_CAMS_0001_P01_B01_02
RUN_CAMS_0001_P01_B01_03
RUN_CAMS_0001_P01_B01_04
RUN_CAMS_0001_P01_B01_05

正式记录设置为：

• sql_version = original
• run_stage = baseline
• run_type = measured
• included_in_metrics = yes

3.4 稳定性判定

基线耗时：

baseline_time_ms = 5 次有效正式执行耗时的中位数

轻量波动率：

variability = (max_time_ms - min_time_ms) / median_time_ms

波动率	状态	处理
≤20%	stable	接受基线
>20% 且 ≤50%	warning	再补跑 5 次
>50%	unstable	暂停对比并排查环境、锁等待或参数

不直接删除异常运行。确认由环境干扰造成后，将 included_in_metrics 改为 no，并填写 exclusion_reason、修改人和修改时间。

4. 结果一致性摘要

4.1 大结果集的 result_hash

不将完整结果集存入 Excel。推荐保存：

returned_rows
result_hash
result_hash_method
result_check_level
result_schema_hash

优先使用“规范化、稳定排序、流式 SHA-256”：

1. 分批读取结果。
2. 统一 NULL、日期、小数、浮点数、字符串和 JSON 格式。
3. 按稳定主键排序。
4. 逐行更新 SHA-256。
5. 只保存最终哈希和行数。

推荐方法标识：

canonical_sorted_sha256_v1

如果没有稳定排序字段，可使用与顺序无关的聚合摘要，并标记校验等级：

result_check_level	方法	自动结论
strong	全量排序后流式 SHA-256	可自动判定一致
medium	行数 + 无序聚合哈希	可自动判定一致，但需保留方法版本
weak	行数 + 关键指标 + 固定抽样	只能判定初步一致

性能测试不要为了哈希而给原 SQL 强行增加排序。结果校验可以作为单独的 validation 运行，不计入性能指标。

如果执行框架能在不改变 execution_time_ms 口径的前提下流式计算哈希，可在正式运行中直接记录；否则五次 measured 只采集性能数据和返回行数，再增加一次 run_type=validation 的校验运行。完整哈希计算耗时不得混入 SQL 性能耗时。

4.2 执行计划摘要

完整 EXPLAIN ANALYZE 每次可能因实际耗时、行数、节点编号、内存和分布式路由变化而不同，不适合直接对全文计算哈希。

使用 plan_structure_hash 代替笼统的 explain_hash。结构哈希只保留：

• 算子类型。
• 表和访问方式。
• 使用的索引。
• Join 顺序与 Join 类型。
• 排序、聚合、临时表。
• 分布式路由和跨分片算子。

排除：

• 实际耗时、成本值和实际行数。
• 节点编号、时间戳、线程数和内存等动态字段。

完整执行计划写入独立文件，Excel 仅保存 explain_file、plan_summary 和 plan_structure_hash。

5. 运行字段语义

5.1 sql_version

表示本次执行的是哪个 SQL 文本版本：

值	含义
original	原始 SQL
opt_r1	第一轮优化 SQL
opt_r2	第二轮优化 SQL
opt_r3	第三轮优化 SQL
final	最终确认版本

同时保存 sql_hash，避免版本名称未变但 SQL 文本被修改。

5.2 run_stage

表示本次执行的业务目的：

值	含义
baseline	生成原 SQL 基线
optimization	测试某轮优化候选
verification	对最终方案进行正式复验
regression	后续回归验证

5.3 run_type

表示这次运行的执行性质：

值	默认纳入性能统计	含义
warmup	否	预热执行
measured	是	正式计时执行
retry	否	异常后的重试
diagnostic	否	EXPLAIN 或排障
validation	否	专门进行结果一致性校验

是否实际进入统计由 included_in_metrics 最终决定。

6. 表一：03_环境台账

6.1 字段定义

字段	必填	示例	说明
environment_id	是	ENV_TDSQL_TEST_20260717_V1	环境唯一编号
db_name	是	tdsql_camsdb	数据库名称
db_mode	是	centralized	部署模式
db_version	是	MySQL 8.0.x	数据库版本
instance_spec	是	8C32G	实例规格
data_snapshot	是	SNAP_20260717	数据快照
index_schema_hash	是	sha256:idx81a2	索引结构摘要
session_config_hash	是	sha256:cfg32b1	会话和关键参数摘要
cache_policy	是	warm_cache	缓存策略
concurrency_mode	是	serial	serial/fixed_concurrency
valid_from	是	2026-07-17 09:00:00	生效时间
valid_to	否	空	失效时间
status	是	active	active/expired/review
owner	是	dba01	环境负责人

6.2 具体示例

environment_id	db_name	db_mode	db_version	instance_spec	data_snapshot	index_schema_hash	session_config_hash	cache_policy	concurrency_mode	valid_from	valid_to	status	owner
ENV_TDSQL_TEST_20260717_V1	tdsql_camsdb	centralized	MySQL 8.0.x	8C32G	SNAP_20260717	sha256:idx81a2	sha256:cfg32b1	warm_cache	serial	2026-07-17 09:00:00		active	dba01

7. 表二：04_运行明细

7.1 字段定义

字段	必填	示例	说明
run_id	是	RUN_CAMS_0001_P01_B01_01	单次运行唯一编号
batch_id	是	20260717_B01	批次
case_id	是	CAMS_0001	SQL Case
parameter_set_id	是	P_CAMS_0001_01	参数集
environment_id	是	ENV_TDSQL_TEST_20260717_V1	环境
baseline_version	是	B01	基线版本
sql_version	是	original	SQL 版本
sql_hash	是	sha256:sql72c8	实际执行 SQL 摘要
run_stage	是	baseline	执行阶段
run_type	是	measured	执行性质
run_sequence	是	1	同组执行序号
execution_time_ms	条件必填	1230	成功执行耗时
success	是	yes	yes/no
returned_rows	条件必填	120	返回行数
result_hash	条件必填	sha256:res91af	validation 必填；measured 可选
result_hash_method	条件必填	canonical_sorted_sha256_v1	有 result_hash 时必填
result_check_level	条件必填	strong	有 result_hash 时必填
result_schema_hash	条件必填	sha256:sch82a1	validation 必填；measured 建议采集
plan_structure_hash	否	sha256:plan789	规范化计划结构摘要
plan_summary	否	index range scan on idx_user_time	执行计划简述
explain_file	否	runs/.../explain.txt	完整计划文件路径
scanned_rows	否	58000	扫描行数
lock_wait_ms	否	2	锁等待
included_in_metrics	是	yes	yes/no
exclusion_reason	否	空	排除统计的原因
error_code	否	空	失败错误码
started_at	是	2026-07-17 10:01:23	开始时间
ended_at	是	2026-07-17 10:01:24	结束时间

7.2 具体示例

run_id	batch_id	case_id	parameter_set_id	environment_id	baseline_version	sql_version	sql_hash	run_stage	run_type	run_sequence	execution_time_ms	success	returned_rows	result_hash	result_hash_method	result_check_level	result_schema_hash	plan_structure_hash	plan_summary	explain_file	scanned_rows	lock_wait_ms	included_in_metrics	exclusion_reason	error_code	started_at	ended_at
RUN_CAMS_0001_P01_B01_W	20260717_B01	CAMS_0001	P_CAMS_0001_01	ENV_TDSQL_TEST_20260717_V1	B01	original	sha256:sql72c8	baseline	warmup	0	1350	yes	120	sha256:res91af	canonical_sorted_sha256_v1	strong	sha256:sch82a1	sha256:plan789	index range scan on idx_user_time	runs/CAMS_0001/B01/warmup-explain.txt	58000	2	no	warmup		2026-07-17 10:00:00	2026-07-17 10:00:02
RUN_CAMS_0001_P01_B01_01	20260717_B01	CAMS_0001	P_CAMS_0001_01	ENV_TDSQL_TEST_20260717_V1	B01	original	sha256:sql72c8	baseline	measured	1	1230	yes	120	sha256:res91af	canonical_sorted_sha256_v1	strong	sha256:sch82a1	sha256:plan789	index range scan on idx_user_time	runs/CAMS_0001/B01/run01-explain.txt	58000	1	yes			2026-07-17 10:01:23	2026-07-17 10:01:24
RUN_CAMS_0001_P01_B01_02	20260717_B01	CAMS_0001	P_CAMS_0001_01	ENV_TDSQL_TEST_20260717_V1	B01	original	sha256:sql72c8	baseline	measured	2	1250	yes	120	sha256:res91af	canonical_sorted_sha256_v1	strong	sha256:sch82a1	sha256:plan789	index range scan on idx_user_time	runs/CAMS_0001/B01/run02-explain.txt	58120	2	yes			2026-07-17 10:02:10	2026-07-17 10:02:12

正式基线还应有序号 3、4、5 三条记录。示例表只展示预热和前两次正式执行，以便阅读。

8. 表三：05_基线汇总

8.1 字段定义

字段	必填	示例	说明
baseline_id	是	BL_CAMS_0001_P01_ENV01_B01	基线唯一编号
batch_id	是	20260717_B01	批次
case_id	是	CAMS_0001	SQL Case
parameter_set_id	是	P_CAMS_0001_01	参数集
environment_id	是	ENV_TDSQL_TEST_20260717_V1	环境
data_snapshot	是	SNAP_20260717	数据快照
baseline_version	是	B01	基线版本
valid_measured_runs	是	5	有效正式运行数
success_runs	是	5	成功运行数
median_time_ms	是	1240	正式基线值
avg_time_ms	是	1242	平均耗时
min_time_ms	是	1200	最小耗时
max_time_ms	是	1280	最大耗时
variability	是	6.45%	简化波动率
baseline_status	是	stable	stable/warning/unstable/blocked
baseline_result_hash	是	sha256:res91af	基线结果摘要
result_hash_method	是	canonical_sorted_sha256_v1	摘要方法
result_check_level	是	strong	校验等级
baseline_plan_structure_hash	否	sha256:plan789	基线计划结构
generated_at	是	2026-07-17 10:10:00	生成时间
generated_by	是	pipeline-job-0717	生成人或任务
note	否	空	补充说明

8.2 具体示例

假设五次正式耗时为 1200、1230、1240、1260、1280 ms：

baseline_id	batch_id	case_id	parameter_set_id	environment_id	data_snapshot	baseline_version	valid_measured_runs	success_runs	median_time_ms	avg_time_ms	min_time_ms	max_time_ms	variability	baseline_status	baseline_result_hash	result_hash_method	result_check_level	baseline_plan_structure_hash	generated_at	generated_by	note
BL_CAMS_0001_P01_ENV01_B01	20260717_B01	CAMS_0001	P_CAMS_0001_01	ENV_TDSQL_TEST_20260717_V1	SNAP_20260717	B01	5	5	1240	1242	1200	1280	6.45%	stable	sha256:res91af	canonical_sorted_sha256_v1	strong	sha256:plan789	2026-07-17 10:10:00	pipeline-job-0717

计算示例：

median_time_ms = MEDIAN(1200,1230,1240,1260,1280) = 1240
avg_time_ms = AVERAGE(1200,1230,1240,1260,1280) = 1242
variability = (1280-1200)/1240 = 6.45%

9. 基线准入规则

只有同时满足以下条件，基线才允许用于优化结果对比：

• valid_measured_runs >= 5。
• success_runs = valid_measured_runs。
• baseline_status = stable。
• 五次运行的 case_id、parameter_set_id、environment_id、data_snapshot 和 sql_hash 一致。
• 五次正式运行的 returned_rows 一致。
• 至少存在一条原 SQL 的有效校验记录，提供 result_hash 和 result_schema_hash；如果五次正式运行均计算哈希，则它们也必须一致。
• result_check_level 为 strong 或 medium。
• 没有未解释的错误、超时或锁等待异常。

weak 校验只能进入人工复核，不能自动认定为功能一致。

10. 基线看板

第一阶段只追踪：

指标	计算方式
待生成基线数	ready SQL 数 - 已有基线状态 SQL 数
基线完成率	stable 基线 SQL 数 ÷ ready SQL 数
基线稳定率	stable 数 ÷ 已执行基线 SQL 数
warning 数	baseline_status=warning
unstable 数	baseline_status=unstable
blocked 数	baseline_status=blocked
强校验覆盖率	strong 基线数 ÷ stable 基线数

建议第一阶段验收标准：

• 100% 的 ready SQL 都有基线状态。
• 至少 90% 形成 stable 基线。
• 所有被排除的运行都有 exclusion_reason。
• 任一基线都能追溯到 1 条预热和至少 5 条正式运行记录。

11. 最小执行清单

1. 在 03_环境台账 登记并确认有效环境。
2. 确认 SQL、参数集、环境和数据快照一致。
3. 完成预检。
4. 执行 1 次预热并记录，但不计入统计。
5. 执行 5 次正式运行并逐条追加到 04_运行明细。
6. 检查成功状态、结果哈希和计划结构。
7. 计算中位数、平均值、极值和波动率。
8. 在 05_基线汇总 生成基线状态。
9. 对 warning 补跑，对 unstable/blocked 排查并保留原因。
10. 基线通过准入规则后，才能进入优化结果对比。