DWS SQL调优最佳实践
DWS SQL 调优对 SQL 语句执行统一诊断，结合语法规范、执行计划和对象元数据，定位性能瓶颈并输出优化建议与优化后 SQL，帮助用户提升 SQL 执行性能。
Skill 地址：hwc-dws-sql-tuning（随 hwc-dws-cli 分发，源码位于 dws-cli 仓库 agent_skills 目录）
前提条件
本 skill 依赖本地 `hwc-dws-cli` 与 DWS 集群连接，未安装或未配置时**直接中止**（无降级模式）。调用前自检：
hwc-dws-cli --version # CLI 是否已安装 hwc-dws-cli config show # 配置文件是否可读 hwc-dws-cli check-con # 集群连接是否正常
先完成配置再调用：
hwc-dws-cli config set # 7步向导：AK/SK → 代理 → Region → 集群 → Endpoint → 连接 → 连通性验证
功能概述
DWS SQL 调优支持两种检查模式，所有模式均需集群连接（执行计划与对象元数据来自集群）
| 检查模式 | 说明 | 规则覆盖 | 触发方式 |
|---|---|---|---|
| full + perf | 用户同意执行 EXPLAIN PERFORMANCE（会实际执行 SQL） | 默认118 条（含 11 条执行计划扩展规则）。 | 诊断调优时回答"允许 EXPLAIN PERFORMANCE"。 |
| full + verbose | 用户拒绝执行 EXPLAIN PERFORMANCE | 107 条（跳过 11 条扩展规则）。 | 诊断调优时回答"仅 EXPLAIN VERBOSE"。 |
默认进入 full 模式并询问是否允许 EXPLAIN PERFORMANCE；用户拒绝则自动切换 full + verbose。
使用方式
在 AI Agent 对话窗口中提供 SQL 文本即可触发调优诊断，支持以下典型用法：
"SQL调优：SELECT ... FROM t1 JOIN t2 ..."
也可通过触发词快速调用：SQL调优、SQL诊断、SQL优化、SQL性能、SQL规范、SQL下推、执行计划、SQL审查、SQL tuning。
调用后交互流程：
检查规则与优化建议解读
默认共 118 条规则，按数据依赖分为四类：
| 类别 | 规则数 | 数据来源 | 规则文件 |
|---|---|---|---|
| 语法检查 | 46 | SQL 文本（静态分析） | syntax_rules.yaml |
| 执行计划检查 | 27 | EXPLAIN VERBOSE | plan_rules.yaml |
| 执行计划扩展检查 | 11 | EXPLAIN PERFORMANCE（需用户确认） | plan_rules_performance.yaml |
| 对象检查 | 34 | 16 静态 AST + 17 系统视图 + 1 语义分析 | object_rules.yaml |
每条规则的完整定义（ID、名称、级别、检查逻辑、修复建议）见规则 YAML 文件，位于 CLI 安装目录：<Python安装目录>\Lib\site-packages\hwc_dws_cli\tuning\rules\
规则配置（可选）
规则由 CLI 统一管理，配置文件位于 ~/.hwc-dws-cli/tuning-config.yaml。skill 在诊断前自动读取该配置：禁用的规则直接跳过，自定义规则参与检查，无需修改 skill 文件即可按需调整诊断范围。
| 操作 | 命令 |
|---|---|
| 查看当前规则配置 | hwc-dws-cli tune config show |
| 禁用内置规则 | hwc-dws-cli tune config set global.tuning.disabled_rules "UPR-001,UOR-15" |
| 重新启用全部规则 | hwc-dws-cli tune config set global.tuning.disabled_rules "[]" |
| 添加自定义规则（单条） | hwc-dws-cli tune config add-rule --id CUS-001 --name "批量UPDATE检查" --category syntax --level error --description "..." --check-logic "..." --fix-suggestion "..." |
| 添加自定义规则（YAML 文件批量） | hwc-dws-cli tune config add-rule --file custom_rules.yaml |
| 移除自定义规则 | hwc-dws-cli tune config remove-rule CUS-001 |
自定义规则要点：
- --check-logic 为判定逻辑描述，skill 诊断时套用该描述执行检查
- 需要集群连接的规则添加 --requires-cluster，并必须提供 --diagnostic-sql（只读 SELECT，支持 {table_names} / {schema_names} / {sql_text} 占位符），skill 会自动执行该 SQL 采集数据后按 check-logic 判定违规
检查报告说明
诊断完成后输出 7 部分报告：
- 诊断结论：违规总数、最严重问题、修复优先级
- SQL 特征：SQL 类型、涉及表数、诊断模式、规则覆盖、数据来源
- 违规详情：按优先级排序（最多 20 条），含规则 ID、级别、问题、证据、修复建议
- 优化建议：按优先级排序，每条含问题/证据/方案/预期
- 优化后 SQL + Hint：优化前后对比、变更 diff、Hint 建议
- 性能验证：优化前后 EXPLAIN PERFORMANCE / VERBOSE 对比（A-time 提升等）
- 统计：各类别规则总数/通过/违规/跳过
报告同时自动保存为 sql_tuning_report_YYYYMMDD_HHMMSS.md。
使用约束与注意事项
- 必须安装 CLI 并配置集群：所有模式均需集群连接；CLI 未安装、连接失败或 EXPLAIN 执行失败时直接中止（无降级模式）。
- EXPLAIN PERFORMANCE 需用户确认：会实际执行 SQL，DML 将修改数据，用户自行判断风险；拒绝后自动切换仅 EXPLAIN VERBOSE。
- 诊断 SQL 只读：15 条诊断 SQL 均为只读 SELECT，查询系统视图。
- 建议流程：先执行 hwc-dws-cli config set（7步向导）配置集群 → check-con 验证连通 → 再调用 skill；性能检查务必先确认 EXPLAIN PERFORMANCE。
