aliyun ⚠️ 执行前就绪检查（所有分析步骤之前完成）：
- 已
pip install hologres-cli，且hologres status能连通目标实例（连接哪个实例 / 库由当前 profile 决定，可用--profile <name>切换）。export HOLOGRES_SKILL=hologres-slow-query-analysis，便于事后审计。RAM 权限、慢日志读授权（
pg_read_all_stats/spm_grant）、版本矩阵、引擎类型语义见 references/preconditions.md。
Hologres 慢 SQL 分析
基于 hologres.hg_query_log 视图分析 Hologres 实例的慢 SQL，输出结构化诊断结论 + 优化建议，回答：哪些 SQL 最值得优先优化、为什么慢、应当怎么优化。所有 SQL 通过 hologres sql run --no-limit-check 执行。
输入参数
| 参数 | 必填 | 说明 |
|---|---|---|
start_time |
是 | 分析开始时间，ISO-8601（北京时间须带 +08:00） |
end_time |
是 | 分析结束时间，格式同 start_time |
query_id |
否 | 单条 SQL 标识；提供时优先做单条 SQL 分析 |
数据库由当前 profile 的
database决定，无需也无法在命令上指定--db-name；换库用hologres config set database <db>或--profile <name>。
决策逻辑
| 输入条件 | 执行流程 | 详见 |
|---|---|---|
未提供 query_id |
实例整体慢 SQL 分析 — 6 步：总体汇总 → 多维画像 → 优先优化对象 → 重点 SQL 深挖 → 错误 SQL 分类 → 最终结论 | references/instance-flow.md |
提供了 query_id |
单条 SQL 分析 — 5 步：定位记录 → 慢因维度判断 → 计划/统计深挖 → 原因总结 → 优化建议 | references/single-query-flow.md |
每个步骤的具体 SQL、输出模板、判定阈值都在对应 references 文件中。每个诊断项都必须输出固定格式的总结，模板见 output-spec.md。
实例整体慢 SQL 分析（intent overview）
| Step | 目的 | 主要查询 / 规则 |
|---|---|---|
| 1 | 拉取时间段内 SQL 总量 / 成功 / 失败 | instance-flow §1 |
| 2 | 按 digest / 用户 / 应用 / SQL 类型 / 读写表 / 资源等多维度做整体画像 | instance-flow §2（独立 SQL 之间应并行执行） |
| 3 | 选出最该优先优化的 SQL（P0 / P1 / P2） | 优先级判定见 diagnosis-rules.md |
| 4 | 对重点 SQL 做 plan / statistics / 资源特征深挖 | instance-flow §4 |
| 5 | 错误 SQL 按 SQLSTATE 分类汇总 | instance-flow §5 + error-codes.md |
| 6 | 输出最终结论 + 优化清单（含 query_id 与完整 SQL 原文，不可截断） |
instance-flow §6 + output-spec.md |
单条 SQL 分析（intent overview）
| Step | 目的 | 关键内容 |
|---|---|---|
| 1 | 通过 query_id 拉取完整记录 |
single-query-flow §1 |
| 2 | 判断慢在哪里（扫描 / 过滤 / 内存 / CPU / 引擎） | duration / read_bytes / memory_bytes / cpu_time_ms / engine_type |
| 3 | 结合 plan / statistics / agg_stats / query_detail / extended_info 深挖慢因 |
引擎子检查清单见 single-query-flow §3 |
| 4 | 输出主 / 次要瓶颈与首要修改点 | 慢因判断规则见 diagnosis-rules.md |
| 5 | 给出可执行的优化建议（核心 / 高收益 / 辅助） | single-query-flow §5 |
输出模板总则
每个诊断项必须采用以下固定格式输出（具体字段在各 step 模板内细化）：
【诊断项名称】
- 指标口径：{统计口径说明}
- 关键结果：{核心数值或 Top 对象（含 query_id）}
- 典型完整 SQL：query_id={...}，SQL={完整 query 原文，不可截断}
- 现象总结：{现象描述}
- 原因判断：{原因分析}
- 建议：{优化建议}
- 结论：{一句话总结}
完整输出规范（标题 / 分析人 / 引擎类型规则 / 实例级 vs 单条 SQL 输出清单）见 references/output-spec.md。
References
| 主题 | 文件 |
|---|---|
前置依赖 / 版本 / 权限 / hg_query_log 字段 / 引擎类型语义 |
preconditions.md |
| 实例整体慢 SQL 分析 6 步流程（含 SQL + 输出模板） | instance-flow.md |
| 单条 SQL 分析 5 步流程（含 SQL + 输出模板） | single-query-flow.md |
| 优先优化规则 + 慢因判断规则 | diagnosis-rules.md |
| 输出规范（标题 / 分析人 / 引擎规则 / 输出清单） | output-spec.md |
| SQLSTATE 错误码完整映射（PostgreSQL + Hologres） | error-codes.md |
| 补充诊断 SQL 库（new-query / 流量 / 高峰期等） | diagnostic-queries.md |
| 慢日志导出（内表 / OSS） | log-export.md |
日志配置参数（log_min_duration_statement 等） |
configuration.md |
注意事项
hologres.hg_query_log默认保留约一个月，单次最多 10000 条；查询必须带query_start范围条件，不要用to_char(query_start, ...)包裹（无法走索引）。engine_type为数组类型，聚合时使用engine_type::text；FixedQE 类 SQL 在慢 SQL 诊断中通常不是瓶颈，建议在 digest 聚合 SQL 中过滤engine_type::text NOT LIKE '%FixedQE%'（详见 instance-flow §2.1）。digest字段从 V2.2 起支持，低版本实例为空，需降级为按query文本聚合。- 输出错误 SQL / 优先优化对象 / 重点 SQL 时，
query原文不可截断，且必须随附query_id。 - 当
hologres sql run返回空结果（无数据）时，禁止自行修改参数重试或变通获取数据；直接跳过该步骤，在输出结果中标注「无数据」。