aliyun/hologres-slow-query-analysis

Hologres 慢 SQL 分析 Skill

前提条件

使用本 Skill 前，需要先安装 hologres-cli：

pip install hologres-cli
export HOLOGRES_SKILL=hologres-slow-query-analysis

所有 SQL 执行和 GUC 参数操作均依赖 hologres-cli 命令（hologres sql run、hologres guc set）。

Hologres 版本要求

| Hologres 版本 | 特性说明 | | :--- | :--- | | V0.10+ | 基础慢查询日志 | | V2.2+ | SQL 指纹（digest） | | V2.2.7+ | 默认阈值 100ms | | V3.0.2+ | <100ms 查询的聚合记录 |

权限要求

查询 hologres.hg_query_log 需要具备相应的读取权限，以下三种方式任选其一：

-- 方式一：授予 Superuser 权限（可查看所有数据库的日志）
ALTER USER "<your_cloud_account_id>" SUPERUSER;

-- 方式二：加入 pg_read_all_stats 用户组（推荐，权限更精细）
GRANT pg_read_all_stats TO "<your_cloud_account_id>";

-- 方式三：仅对当前数据库生效（SPM 权限模型）
CALL spm_grant('<db_name>_admin', '<your_cloud_account_id>');

目标

基于 hologres.hg_query_log 视图，对 Hologres 实例中的慢 SQL 进行分析，支持两种模式：

1. 实例整体慢 SQL 分析
   • 当用户未提供 query_id 时，默认分析指定时间范围内实例整体慢 SQL 情况
2. 单条 SQL 分析
   • 当用户提供了 query_id 时，默认分析该 SQL 的执行情况、资源消耗、执行计划和优化建议

本 Skill 的目标不仅是找出慢 SQL，还要回答：

• 这段时间内 SQL 总体情况如何
• 哪些 SQL 最值得优先优化
• 为什么慢
• 慢在什么地方
• 应该怎么优化
• 每个诊断项的结果是什么
• 错误 SQL 的报错和原因是什么

---

适用场景

当用户需要以下能力时，使用本 Skill：

• 分析某个时间段内的慢 SQL
• 找出实例里最慢、最重、最值得优化的 SQL
• 分析指定 query_id 的 SQL 慢因
• 从资源消耗、执行计划、表维度等角度定位问题
• 输出可执行的优化建议
• 对每个诊断项给出明确总结
• 分析错误 SQL 的报错和原因

---

输入参数

必填

• start_time：分析开始时间
• end_time：分析结束时间

选填

• query_id：SQL 标识；如果提供，则优先分析该单条 SQL

---

决策逻辑

情况一：未提供 query_id

执行实例整体慢 SQL 分析：

• 统计指定时间段内的 SQL 总量、成功数量、失败数量
• 找出 TOP 慢 SQL / TOP 总耗时 SQL
• 分析用户、应用、SQL 类型、表等维度
• 找出最值得优先优化的 SQL
• 分析错误 SQL 的报错和原因
• 给出整体优化建议
• 每个诊断项都要输出总结

情况二：提供了 query_id

执行单条 SQL 分析：

• 精确定位该 SQL
• 分析其耗时、扫描量、返回量、资源消耗
• 查看执行计划、诊断信息、读写表
• 解释该 SQL 为什么慢
• 给出针对性的优化建议
• 每个诊断项都要输出总结

---

数据源

主要使用视图：hologres.hg_query_log

关键字段说明

标识类字段

• query_id：SQL 唯一标识
• digest：SQL 指纹
• usename：用户名
• application_name：应用名
• client_addr：客户端地址
• datname：数据库名
• command_tag：SQL 类型
• status：执行状态
• message：错误信息

时间类字段

• query_start：开始时间
• query_end：结束时间
• duration：执行耗时
• query_date：日期

SQL 原文

• query：SQL 文本

资源与执行特征字段

• result_rows：返回行数
• result_bytes：返回字节数
• read_rows：读取行数
• read_bytes：读取字节数
• affected_rows：影响行数
• affected_bytes：影响字节数
• memory_bytes：内存消耗
• shuffle_bytes：Shuffle 数据量
• cpu_time_ms：CPU 时间
• physical_reads：物理读

表相关字段

• table_read：读到的表数组
• table_write：写入的表

执行计划与诊断字段

• plan
• statistics
• agg_stats
• visualization_info
• query_detail
• query_extinfo
• extended_info
• extended_cost

引擎类型说明

在单条 SQL 分析中，需要分析 engine_type，判断 SQL 使用了哪些引擎：

HQE

• Hologres 原生自研引擎
• 大多数查询通过 HQE 实现
• HQE 执行效率较高
• 如果 SQL 主要走 HQE，通常说明执行路径较优

PQE

• PostgreSQL 引擎
• 说明有部分 SQL 算子或表达式在 PQE 执行
• 一般是因为存在 HQE 未原生支持的算子或表达式
• 如果出现 PQE，应考虑是否能通过改写函数或表达式让 SQL 回到 HQE，以提升执行效率

SDK / FixedQE

• Fixed Plan 的执行引擎
• 适合高效执行点读、点写、PrefixScan 等偏 Serving 类型的 SQL
• 从 Hologres V2.2 开始，SDK 执行引擎正式更名为 FixedQE
• 如果 SQL 属于 Serving 场景，使用 SDK/FixedQE 可能是合理的

PG

• Frontend 本地计算
• 一般用于读取系统表元数据查询，不读取用户表数据
• 只占用极少系统资源
• 需要注意：DDL 也会使用 PostgreSQL 引擎
• 如果用户 SQL 走 PG，通常要判断是否属于系统元数据查询或 DDL

---

分析流程

一、实例整体慢 SQL 分析流程

当没有提供 query_id 时，按以下流程执行。

第 1 步：拉取时间段内 SQL 总体汇总

统计指定时间范围内的：

• SQL 总量
• 成功数量
• 失败数量

该项输出模板

【总体汇总】
- 时间范围：{start_time} ~ {end_time}
- SQL 总量：{total_sql_cnt}
- 成功数量：{success_sql_cnt}
- 失败数量：{failed_sql_cnt}
- 成功率：{success_rate}
- 失败率：{failed_rate}
- 结论：{summary}

推荐查询 SQL

SELECT
  COUNT(*) AS total_sql_cnt,
  COUNT(*) FILTER (WHERE status = 'success') AS success_sql_cnt,
  COUNT(*) FILTER (WHERE status <> 'success') AS failed_sql_cnt
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}';

第 2 步：做整体画像分析

从以下维度分析慢 SQL 分布特征：

• 慢 SQL 总量
• 平均耗时 / 最大耗时
• 单次最慢 SQL
• 按 digest 聚合后的总耗时最高 SQL
• 按 usename 分布
• 按 application_name 分布
• 按 command_tag 分布
• 按 table_read / table_write 分布
• 按资源消耗特征分布
• 错误状态分布

该项输出模板

【{诊断项名称}】
- 指标口径：{统计口径说明}
- 关键结果：{核心数值或Top对象，每条需包含 query_id（示例）}
- 典型完整 SQL（含 query_id）：query_id={sample_query_id}，SQL={从该类别中选取一条具有代表性的 SQL，输出完整 query 原文，不可截断}
- 现象总结：{现象描述}
- 原因判断：{原因分析}
- 建议：{优化建议}
- 结论：{一句话总结}

第 3 步：找出最该优先优化的 SQL

优先考虑以下 SQL：

1. 单次耗时高且资源消耗高
2. 按 digest 聚合后总耗时高
3. 扫描量大但返回少
4. CPU / 内存高
5. 物理读高

该项输出模板

【优先优化对象】
- 优先级：{P0/P1/P2}
- SQL 标识：{query_id}
- 对应 digest：{digest}（如有）
- SQL 原文：{query}
- 耗时：{duration}
- 资源特征：{read_bytes / memory_bytes / cpu_time_ms / physical_reads}
- 入选原因：{为什么优先}
- 优化建议：{建议}

第 4 步：对重点 SQL 做进一步诊断

重点查看：

• query
• plan
• statistics
• agg_stats
• query_detail
• query_extinfo
• extended_info
• table_read
• table_write

该项输出模板

【重点 SQL 诊断】
- SQL 标识：{query_id}
- SQL 原文：{query}
- 主要现象：{慢的表现}
- 执行计划特征：{plan/diagnostic summary}
- 资源特征：{扫描/CPU/内存/IO}
- 慢因判断：{原因}
- 优化建议：{建议}

第 5 步：输出错误 SQL 分析（按错误类型分类）

对 status <> 'success' 的 SQL 进行分析，先按 SQLSTATE 错误码分类汇总，再逐一分析。

错误码提取方式

从 message 字段中提取 5 位 SQLSTATE 错误码：

ltrim(split_part(message, ': ', 2), ' ') AS error_code

常见 Error Code 与错误类型映射

| SQLSTATE Code | 错误类型 | 说明 | 常见的完整报错 | 解决方法 | | :--- | :--- | :--- | :--- | :--- | | HG_ERRCODE_FDW_ERROR | 外部表元数据导入错误 | MaxCompute 外部表的元数据导入至 Hologres 时产生报错，通常是由于不支持某种类型的表所导致。 | failed to import foreign schema from odps: Can't find file system factory | 详情请参见 HG_ERRCODE_FDW_ERROR 文档。 | | HV000 | ERRCODE_FDW_ERROR | 外部表查询出现报错。 | failed to import foreign schema from odps: Authorization Failed: xxx<br>failed to import foreign schema from odps: Table not found -xxx | 根据具体的报错解决，详情请参见 ERRCODE_FDW_ERROR 文档。 | | 23505 | ERRCODE_UNIQUE_VIOLATION | 违反唯一性约束，常出现在写入时主键重复的场景。 | duplicate key value violates unique constraint DETAIL: xxx already exists. | 处理主键重复的数据。若是 INSERT 语法报错，可以改写成 insert into xx on conflict 的语法，实现主键去重。 | | 23514 | ERRCODE_CHECK_VIOLATION | 违反检查约束，常发生在写入 Hologres 分区表时，写入的分区值与设置的分区值不一致。 | new row for relation xx violates partition constraint DETAIL: Failing row contains (column1)=(xxxx). | 需要检查分区数据和设置的分区值是否一致，并修改为一致。 | | 23502 | ERRCODE_NOT_NULL_VIOLATION | 违反非空约束。常发生在非空（not null）字段写入了空（null）数据。 | null value in column xxx violates not-null constraint DETAIL: Failing row contains (null). | 处理脏数据。 | | 42P01 | ERRCODE_UNDEFINED_TABLE | 表不存在，一般出现在表刚刚创建未更新元数据或者 Query 执行过程中，表有 TRUNCATE 或 DROP 的场景。 | Dispatch query failed: Table not found | 可以使用 Query 洞察排查是否有同时 TRUNCATE 或 DROP 任务，然后重试任务。 | | XX000 | ERRCODE_INTERNAL_ERROR | 内部非预期错误，实例可能出现过宕机或者 Query 被意外中断。 | Transaction xx is not found or it was expired and cancelled.<br>Query is cancelled<br>ERPC_ERROR_CONNECTION_CLOSED | 非预期的内部错误，可以提工单排查。 | | 57014 | ERRCODE_QUERY_CANCELED | 查询被取消，一般是因为设置了客户端超时，或者表被 TRUNCATE 或 DROP 了。 | ERROR: canceling statement due to statement timeout<br>canceling statement due to user request | 检查是否设置了 statement_timeout，或排查是否有并发的 TRUNCATE/DROP 操作。 | | 0A000 | ERRCODE_FEATURE_NOT_SUPPORTED | 有某个功能不支持。 | Dynamic partition selector is not supported<br>ALTER TABLE CHANGE OWNER is not supported in SPM | 根据具体报错确认功能是否支持，改用其他等效方案。 | | 42704 | ERRCODE_UNDEFINED_OBJECT | 存在未定义的对象，一般是列不存在、Table Group 不存在。 | column xxx does not exist<br>Table group xxx does not exist. | 请先创建提示不存在的对象。确认报错不存在的对象在 SQL 中是否填写了正确名称。 | | 42501 | ERRCODE_INSUFFICIENT_PRIVILEGE | 当前账号权限不足，需要授权。 | ERROR: permission denied for schema xxx<br>ERROR: permission denied for foreign table table_info | 联系管理员授予对应权限。 | | 53200 | ERRCODE_OUT_OF_MEMORY | Query 因为内存不足，出现了 OOM。 | Total memory used by all existing queries exceeded memory limitation | 优化 SQL 降低内存消耗，或降低并发度。详情请参见 OOM 常见问题排查指南。 | | 42804 | ERRCODE_DATATYPE_MISMATCH | 类型不匹配，通常为表达式需要的类型与字段的实际类型不匹配。 | unmatched data row schema number<br>Datasets has different schema | 检查 SQL 的列是否匹配。 | | 22012 | ERRCODE_DIVISION_BY_ZERO | SQL 中存在除数为 0 的情况。 | division by zero | 处理脏数据，或者使用 GUC 使除以 0 不报错。 | | 22001 | ERRCODE_STRING_DATA_RIGHT_TRUNCATION | 字符串右截断，多发生于 VARCHAR 字段的实际值超过了建表时 VARCHAR 指定的长度。 | value too long for type character varying(xx) | 重新建表修改 VARCHAR 字段的长度，或者将字段类型设置为 TEXT。 | | 54000 | ERRCODE_PROGRAM_LIMIT_EXCEEDED | 超过 Hologres 允许的上限，通常发生在扫描外部表分区表数量、读的行数、读的字节等超过上限。 | number of read rows (xxxxx) exceeds limit (xxxxxxx)<br>number of partitions (xxx) scanned for "xxxx" exceeds the maximum allowed (xxx) | 外部表查询超过了限制，解决方法请参见对接 MaxCompute 常见问题与诊断。 | | 42601 | ERRCODE_SYNTAX_ERROR | SQL 语法错误。 | syntax error at or near "xxxxx" | 请您重新检查 SQL 语法。 | | 42883 | ERRCODE_UNDEFINED_FUNCTION | 一般为不支持的函数功能，可能是因为函数语法使用错误，或者未创建 Extension 等，也可能是不支持某个函数。 | function xxxxx does not exist<br>operator does not exist: xxxxxx | 请根据函数的语法进行操作，避免语法错误或者 Extension 未创建等。 | | 2F003 | ERRCODE_E_R_E_READING_SQL_DATA_NOT_PERMITTED | 没有外部表的读权限。 | check permission for foreign table scan failed: failed to check permission: MaxCompute error, Authorization Failed [4019], You have NO privilege 'odps:Select' on {xxxxxxxxxx} | 联系 ODPS/MaxCompute 管理员开通对应权限。 | | 42710 | ERRCODE_DUPLICATE_OBJECT | 存在重复的对象，通常发生于创建重复的 Extension、Publication、Role 等。 | publication "xxxxx" already exists<br>extension "xxxxx" already exists | 如果对象已经存在，不需要重复创建。 | | 22P02 | ERRCODE_INVALID_TEXT_REPRESENTATION | 非法的文本表达式，常发生于字符串转换为其他类型时，字符串的数据非法，比如空字符串（""）转 INT。 | invalid input syntax for integer: xxx | 处理脏数据。 | | 22P04 | ERRCODE_BAD_COPY_FILE_FORMAT | 执行 copy 命令时文件或数据的格式不正确，多发生于数据本身就包含了 copy 指定的分割符（比如空格），导致列的数量对不上。 | extra data after last expected column. failed to query next<br>missing data for column "xxx". failed to query next | 处理脏数据。 | | 42703 | ERRCODE_UNDEFINED_COLUMN | Query 中有不存在的列。 | column xxxxx does not exist | 重新检查 SQL 语法。 | | 22003 | ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE | 数值类型超过范围：numeric 类型数据超过了 numeric 定义的范围，或者 int/bigint 超过了表示范围。 | value "xxxxx" is out of range for type bigint<br>numeric field overflow | 检查是否有脏数据或者类型定义错误，重新修改列类型。 | | 22008 | ERRCODE_DATETIME_FIELD_OVERFLOW | timestamp、timestamptz、date、time、timetz 等时间相关的字段存在值溢出。 | date/time field value out of range: "xxxxxx" | 处理脏数据。 | | 22023 | ERRCODE_INVALID_PARAMETER_VALUE | 非法参数值，一般是各种情况下的参数不符合要求。 | column "col" with type "float4" cannot be set as "bitmap_columns" | 重新检查 SQL 语法和参数设置。 | | 22007 | ERRCODE_INVALID_DATETIME_FORMAT | 非法的日期格式，日期数据不符合格式要求。 | invalid input syntax for type timestamp: ""<br>invalid value "" for "yyyy", Value must be an integer. | 处理脏数据。 | | 22021 | ERRCODE_CHARACTER_NOT_IN_REPERTOIRE | 字符不在编码范围，常见于出现了 UTF-8 编码之外的非法字符。 | invalid byte sequence for encoding "UTF8": 0xe9 0x80 | 处理脏数据。 | | 42P07 | ERRCODE_DUPLICATE_TABLE | 重复的表，常见表已经存在时，又重复建同名表。 | relation "xxxx" already exists | 如果表已经存在，则不需要重复创建。 | | 22P05 | ERRCODE_UNTRANSLATABLE_CHARACTER | 存在字符无法转化为目标格式。 | character with byte sequence 0xe4 0x9e 0xab in encoding "UTF8" has no equivalent in encoding "GBK" | 处理脏数据。 | | 42803 | ERRCODE_GROUPING_ERROR | 分组错误，group by 相关的错误。 | column "xxx" must appear in the GROUP BY clause or be used in an aggregate function | 重新检查 SQL 语法，聚合函数的字段需要包含在 group by 内。 | | 25001 | ERRCODE_INVALID_TRANSACTION_STATE | 非法的事务状态。涉及事务的相关操作非法。 | SET_TABLE_PROPERTY and CREATE TABLE statement are not in the same transaction | create table 语句需要和 CALL SET_TABLE_PROPERTY 在一个事务里（使用 begin; 和 commit;）。 | | 42702 | ERRCODE_AMBIGUOUS_COLUMN | 模棱两可的列。一般是 SQL 中同一列名可能是不同列时报错。 | column reference "xxx" is ambiguous | 重新检查 SQL 语法，明确指定列所属的表。 | | 42701 | ERRCODE_DUPLICATE_COLUMN | 重复列，常发生在建表时同一字段声明了多次。 | column "xxx" specified more than once | 重新检查 SQL 语法。 | | 42725 | ERRCODE_AMBIGUOUS_FUNCTION | 模棱两可的函数。一般是函数支持多种类型的入参，但传参的类型没有指定清楚。 | function xxx does not exist（因入参类型不明确） | 重新检查 SQL 语法，显式指定类型转换。 | | 42611 | ERRCODE_INVALID_COLUMN_DEFINITION | 非法的列定义，在 Hologres 中多是 Numeric 或 Decimal 类型未指明精度。 | invalid definition of a numeric type | 处理脏数据。 | | 3D000 | ERRCODE_INVALID_CATALOG_NAME / ERRCODE_UNDEFINED_DATABASE | 指定的数据库不存在。 | — | 检查数据库是否存在。 | | 42846 | ERRCODE_CANNOT_COERCE | 两个类型数据之间无法转化时报错。 | cannot cast type date to integer | 重新检查 SQL 语法。 | | 2BP01 | ERRCODE_DEPENDENT_OBJECTS_STILL_EXIST | 依赖的对象仍存在，常见于删除一个对象时，依赖其的对象仍然存在。 | — | 处理相关依赖，先删除依赖对象再删除目标对象。 | | 3F000 | ERRCODE_UNDEFINED_SCHEMA | 指定的 Schema 不存在。 | schema "xxxx" does not exist | 检查 Schema 是否存在，不存在需要先创建。 | | 42P04 | ERRCODE_DUPLICATE_DATABASE | 重复的数据库，创建一个已存在的数据库时报错。 | — | 如果数据库已经存在，无需重复创建。 | | — | AutoAnalyze-Failed | Auto Analyze 因为某些原因失败。 | query row count from analyze table<br>query from analyze table | Auto Analyze 失败，一般为后端原因，请提工单排查。 | | — | Import Foreign Table Not Found | 找不到外部表。 | failed to get foregin table split: Table not found<br>Failed to get odps table: Not enable acid table | 请检查访问的外部表的是否存在。 | | — | Cannot Acquire Lock In Time | 这个异常通常是由于拿锁失败，高并发查询和删除（Drop）同一张表时，后端节点出现死锁，导致有关这张表的操作都卡住，从而报错。 | internal error: Cannot acquire lock in time, current owners | 解决方法请参见锁以及排查锁。 | | — | OTHER | 非预期的报错。 | kConnectError: channel is empty<br>ERPC_ERROR_CONNECTION_CLOSED<br>internal error: Connect timeout | 非预期的报错，可以提工单排查。 |

完整映射表见 error-codes.md。

错误码分类汇总 SQL

SELECT
  ltrim(split_part(message, ': ', 2), ' ') AS error_code,
  count(*) AS error_count,
  min(query_start) AS first_seen,
  max(query_start) AS last_seen,
  count(DISTINCT usename) AS affected_users
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start < TIMESTAMPTZ '{end_time}'
  AND status = 'FAILED'
GROUP BY 1
ORDER BY 2 DESC
LIMIT 20;

该项输出模板

【错误 SQL 按错误类型分类】
- 指标口径：按 SQLSTATE 错误码归类，统计每类错误的失败数量、涉及用户、首次/末次出现时间
- 关键结果：
  | 错误类型 (SQLSTATE) | 失败数 | 涉及用户 | 首次出现 | 末次出现 | 典型报错 |
  | :--- | :--- | :--- | :--- | :--- | :--- |
  | {error_type} ({sqlstate}) | {cnt} | {affected_users} | {first_seen} | {last_seen} | {sample_error} |
- 典型完整 SQL（含 query_id）：query_id={sample_query_id}，SQL={从该类别中选取一条具有代表性的 SQL，输出完整 query 原文，不可截断}
- 现象总结：{各类错误占比和集中度}
- 原因判断：{错误根因分析}
- 建议：{针对性修复建议}
- 结论：{一句话总结}

第 6 步：输出结论和建议（合并优化清单）

输出应明确包含：

• 哪些 SQL 最慢
• 哪些 SQL 最值得优先优化
• 慢因是什么
• 错误 SQL 的报错和原因是什么
• 应该如何优化
• 每个优化对象必须给出具体的 query_id 和完整 SQL 原文
• 优化对象和最终结论合并到同一个章节输出

该项输出模板

【最终结论与优化建议】
- 时间范围：{start_time} ~ {end_time}
- 总体情况：{summary}
- 主要瓶颈：{瓶颈}

### 需要整改的 SQL 清单

#### P0 - 立即处理
**{表名/SQL标识}**（{错误类型简述}）
- query_id：{query_id}
- 完整 SQL：{完整 SQL 原文，不可截断，必须包含全部 query 内容}
- 报错信息：{message}
- 错误类型：{语法/权限/资源/超时/对象不存在/其他}
- 整改动作：{具体处理建议}

#### P1 - 观察监控
**{表名/SQL标识}**（{现象简述}）
- query_id：{query_id}
- 完整 SQL：{完整 SQL 原文，不可截断}
- 状态：{SUCCESS/FAILED}，耗时 {duration}
- 整改动作：{监控/优化建议}

### DROP/修复命令参考（如适用）
```sql
{可直接执行的 DDL/DML 命令}

总体建议

1. 立即处理：{优先级最高的动作}
2. 监控观察：{需要持续关注的对象}
3. 例行维护：{长期优化建议}

## 二、单条 SQL 分析流程

当提供了 `query_id` 时，按以下流程执行。

### 第 1 步：定位 SQL 记录

通过 `query_id` 精确查询对应 SQL。

#### 该项输出模板

【SQL 基本信息】

• SQL 标识：{query_id}
• SQL 原文：{query}
• 用户：{usename}
• 应用：{application_name}
• 客户端：{client_addr}
• 状态：{status}
• 执行时间：{query_start} ~ {query_end}
• 耗时：{duration}
• 结论：{summary}

### 第 2 步：判断该 SQL 是否慢、慢在哪里

关注以下指标：
- `duration`
- `read_rows`
- `read_bytes`
- `result_rows`
- `result_bytes`
- `memory_bytes`
- `cpu_time_ms`
- `physical_reads`
- `engine_type`

#### 该项输出模板

【慢因诊断】

• 扫描情况：{是否扫描过大}
• 过滤情况：{是否有效过滤}
• Join 情况：{是否Join代价高}
• 聚合/排序情况：{是否有大聚合/排序}
• 内存情况：{是否有内存压力}
• CPU 情况：{是否有CPU压力}
• 表设计/SQL写法：{是否存在问题}
• 引擎分析：{HQE/PQE/SDK/PG 的使用情况与影响}
• 结论：{summary}

### 第 3 步：分析慢因

结合以下信息进行诊断：
- SQL 原文 `query`
- 执行计划 `plan`
- 统计信息 `statistics`
- 聚合信息 `agg_stats`
- 执行细节 `query_detail`
- 扩展诊断 `query_extinfo`
- 扩展信息 `extended_info`
- 读写表信息 `table_read`、`table_write`

#### 该项输出模板

【慢因诊断】

• 扫描情况：{是否扫描过大}
• 过滤情况：{是否有效过滤}
• Join 情况：{是否Join代价高}
• 聚合/排序情况：{是否有大聚合/排序}
• 内存情况：{是否有内存压力}
• CPU 情况：{是否有CPU压力}
• 执行引擎情况：{查询的sql推荐使用高性能执行引擎HQE}
• 表设计/SQL写法：{是否存在问题}
• 结论：{summary}

#### 引擎分析说明

单条 SQL 分析中，`engine_type` 是必须分析项：
- 如果出现 PQE
    - 说明 SQL 中有部分逻辑未走 HQE
    - 优先判断是否存在：
        - 不支持的函数
        - 不支持的表达式
        - 复杂类型转换
        - 无法下推的算子
    - 可尝试改写 SQL 让更多逻辑进入 HQE
- 如果主要是 SDK / FixedQE
    - 说明 SQL 更偏 Serving 访问模式
    - 如果业务场景符合点查、前缀扫描等，可认为合理
    - 如果不是 Serving 场景，则需要看是否存在优化空间
- 如果是 PG
    - 说明可能是系统表查询或 DDL
    - 若是用户数据查询却走 PG，需要重点关注
- 如果主要是 HQE
    - 通常说明执行路径较优
    - 仍需结合资源指标和执行计划判断是否存在其他瓶颈

### 第 4 步：输出原因判断

说明该 SQL 慢的主要原因，例如：
- 扫描量大
- 返回量少
- Join 成本高
- 聚合 / 排序重
- 内存占用高
- CPU 消耗高
- 表设计不合理
- SQL 写法不合理

#### 该项输出模板

【原因总结】

• 主瓶颈：{primary_reason}
• 次要瓶颈：{secondary_reason}
• 解释：{why_slow}
• 最优先修改点：{first_action}

### 第 5 步：输出优化建议

给出可执行的优化建议，例如：
- 增加过滤条件
- 减少扫描列 / 扫描行
- 调整 Join 顺序
- 减少数据量
- 调整表分布键 / 分区键 / 索引
- 减少返回数据量
- 采用预聚合或拆分查询

#### 该项输出模板

【优化建议】

• 最核心优化点：{core_suggestion}
• 高收益建议：{high_value_suggestions}
• 辅助建议：{secondary_suggestions}
• 优先级顺序：{priority_order}
• 结论：{summary}

---

## 参考文档

| 文档 | 内容 |
| :--- | :--- |
| [error-codes.md](references/error-codes.md) | SQLSTATE 错误码 → 错误类型完整映射表（PostgreSQL + Hologres） |
| [diagnostic-queries.md](references/diagnostic-queries.md) | 完整诊断 SQL 集合 |
| [log-export.md](references/log-export.md) | 导出日志到内外部表 |
| [configuration.md](references/configuration.md) | 配置参数说明 |

---

# 推荐查询 SQL

### 1、查询指定时间段内 SQL 总体汇总
```sql
SELECT
  COUNT(*) AS total_sql_cnt,
  COUNT(*) FILTER (WHERE status = 'success') AS success_sql_cnt,
  COUNT(*) FILTER (WHERE status <> 'success') AS failed_sql_cnt
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}';

2、按 digest 聚合，找总耗时最高的 SQL 模板（含 engine_type，排除 FixedQE）

SELECT
  digest,
  (array_agg(query_id ORDER BY duration DESC))[1] AS sample_query_id,
  command_tag,
  (array_agg(engine_type::text ORDER BY duration DESC))[1] AS sample_engine_type,
  COUNT(*) AS exec_cnt,
  AVG(duration)::bigint AS avg_duration,
  MAX(duration) AS max_duration,
  SUM(duration) AS total_duration,
  SUM(read_rows) AS total_read_rows,
  SUM(read_bytes) AS total_read_bytes,
  SUM(result_rows) AS total_result_rows,
  SUM(cpu_time_ms) AS total_cpu_time_ms,
  SUM(memory_bytes) AS total_memory_bytes,
  (array_agg(query ORDER BY duration DESC))[1] AS sample_query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start < TIMESTAMPTZ '{end_time}'
  AND digest IS NOT NULL
  AND (engine_type IS NULL OR engine_type::text NOT LIKE '%FixedQE%')
GROUP BY digest, command_tag
ORDER BY total_duration DESC
LIMIT 20;

说明：engine_type 为数组类型，聚合时需使用 engine_type::text 转换。

FixedQE 过滤原因：Fixed Plan（FixedQE）引擎专为点查/点写优化，其 SQL 特征为 unnest 批量 INSERT 或单条点查。这类 SQL 执行频次极高（日均数十万~数百万次），累计总耗时大，但单次平均耗时通常在几百毫秒内，属于正常的业务 Serving 负载。在慢 SQL 诊断中，FixedQE 类 SQL 通常不是性能瓶颈的重点，因此本 SQL 主动过滤掉 FixedQE，让诊断聚焦于 HQE（分析型查询） 和 PG（系统/后台任务） 等真正需要深入分析的引擎类型。

如需单独查看 FixedQE 的执行情况，可去掉 AND (engine_type IS NULL OR engine_type::text NOT LIKE '%FixedQE%') 条件另行查询。

3、按单次耗时找最慢 SQL（含 engine_type）

SELECT
  query_id,
  digest,
  usename,
  application_name,
  command_tag,
  engine_type,
  duration,
  read_rows,
  read_bytes,
  result_rows,
  result_bytes,
  cpu_time_ms,
  memory_bytes,
  physical_reads,
  query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
ORDER BY duration DESC
LIMIT 20;

说明：分析时需结合 engine_type 判断 SQL 使用的执行引擎。HQE 类查询重点关注扫描量、内存、CPU 和执行计划；FixedQE 类查询（点查/点写）若耗时异常高，优先检查并发压力和锁竞争；PG 类查询（ANALYZE/系统表查询）耗时高通常与表数据量或元数据操作相关。

4、按用户分析

SELECT
  usename,
  COUNT(*) AS slow_sql_cnt,
  SUM(duration) AS total_duration,
  AVG(duration) AS avg_duration,
  SUM(read_bytes) AS total_read_bytes,
  SUM(cpu_time_ms) AS total_cpu_time_ms,
  (array_agg(query_id ORDER BY duration DESC))[1] AS sample_query_id,
  (array_agg(query ORDER BY duration DESC))[1] AS sample_query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
GROUP BY usename
ORDER BY total_duration DESC;

5、按应用分析

SELECT
  application_name,
  COUNT(*) AS slow_sql_cnt,
  SUM(duration) AS total_duration,
  AVG(duration) AS avg_duration,
  (array_agg(query_id ORDER BY duration DESC))[1] AS sample_query_id,
  (array_agg(query ORDER BY duration DESC))[1] AS sample_query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
GROUP BY application_name
ORDER BY total_duration DESC;

6、按 SQL 类型分析

SELECT
  command_tag,
  COUNT(*) AS cnt,
  SUM(duration) AS total_duration,
  AVG(duration) AS avg_duration,
  SUM(read_bytes) AS total_read_bytes,
  SUM(cpu_time_ms) AS total_cpu_time_ms,
  (array_agg(query_id ORDER BY duration DESC))[1] AS sample_query_id,
  (array_agg(query ORDER BY duration DESC))[1] AS sample_query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
GROUP BY command_tag
ORDER BY total_duration DESC;

7、按读表分析

SELECT
  t.table_name,
  COUNT(*) AS slow_sql_cnt,
  SUM(l.duration) AS total_duration,
  AVG(l.duration) AS avg_duration,
  SUM(l.read_bytes) AS total_read_bytes,
  SUM(l.cpu_time_ms) AS total_cpu_time_ms,
  (array_agg(l.query_id ORDER BY l.duration DESC))[1] AS sample_query_id,
  (array_agg(l.query ORDER BY l.duration DESC))[1] AS sample_query
FROM hologres.hg_query_log l
CROSS JOIN LATERAL unnest(l.table_read) AS t(table_name)
WHERE l.query_start >= TIMESTAMPTZ '{start_time}'
  AND l.query_start <  TIMESTAMPTZ '{end_time}'
GROUP BY t.table_name
ORDER BY total_duration DESC
LIMIT 20;

8、按写表分析

SELECT
  table_write,
  COUNT(*) AS slow_sql_cnt,
  SUM(duration) AS total_duration,
  AVG(duration) AS avg_duration,
  SUM(affected_rows) AS total_affected_rows,
  SUM(affected_bytes) AS total_affected_bytes,
  (array_agg(query_id ORDER BY duration DESC))[1] AS sample_query_id,
  (array_agg(query ORDER BY duration DESC))[1] AS sample_query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
  AND table_write IS NOT NULL
GROUP BY table_write
ORDER BY total_duration DESC;

9、扫描量最大的 SQL

SELECT
  query_id,
  digest,
  duration,
  read_rows,
  read_bytes,
  result_rows,
  result_bytes,
  query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
ORDER BY read_bytes DESC
LIMIT 20;

10、内存消耗最高的 SQL

SELECT
  query_id,
  digest,
  duration,
  memory_bytes,
  cpu_time_ms,
  query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start <  TIMESTAMPTZ '{end_time}'
ORDER BY memory_bytes DESC, duration DESC
LIMIT 20;

11、异常状态分析（主要分析错误 SQL）

-- 提取错误码并按类型汇总
SELECT
  ltrim(split_part(message, ': ', 2), ' ') AS error_code,
  count(*) AS error_count,
  min(query_start) AS first_seen,
  max(query_start) AS last_seen,
  count(DISTINCT usename) AS affected_users
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start < TIMESTAMPTZ '{end_time}'
  AND status = 'FAILED'
GROUP BY 1
ORDER BY 2 DESC
LIMIT 20;

-- 按错误码分类查看具体错误 SQL
SELECT
  query_id,
  digest,
  ltrim(split_part(message, ': ', 2), ' ') AS error_code,
  duration,
  status,
  message,
  query
FROM hologres.hg_query_log
WHERE query_start >= TIMESTAMPTZ '{start_time}'
  AND query_start < TIMESTAMPTZ '{end_time}'
  AND status <> 'success'
ORDER BY query_start DESC;

12、按 query_id 查询单条 SQL 详情

SELECT
  query_id,
  digest,
  usename,
  application_name,
  client_addr,
  status,
  command_tag,
  duration,
  query_start,
  query_end,
  read_rows,
  read_bytes,
  result_rows,
  result_bytes,
  cpu_time_ms,
  memory_bytes,
  shuffle_bytes,
  physical_reads,
  table_read,
  table_write,
  query,
  plan,
  statistics,
  agg_stats,
  query_detail,
  query_extinfo,
  extended_info,
  visualization_info,
  extended_cost
FROM hologres.hg_query_log
WHERE query_id = '{query_id}';

---

优先优化规则

当没有提供 query_id 时，建议按以下顺序判断"最该优先优化的 SQL"：

第一优先

• duration 高
• read_bytes 高
• memory_bytes 高
• cpu_time_ms 高
• physical_reads 高

第二优先

• 按 digest 聚合后 SUM(duration) 高
• 执行频次高
• 总资源消耗高

第三优先

• read_rows / result_rows 比值很高
• 扫描很多、返回很少

第四优先

• 反复出现在 table_read 中的热点表
• 慢 SQL 集中访问的重点表

---

慢因判断规则

• 扫描过大
  • read_rows、read_bytes 很高
• 过滤不够好
  • read_rows / result_rows 很高
• 内存压力大
  • memory_bytes 很高
• IO 压力大
  • physical_reads 很高
• CPU 压力大
  • cpu_time_ms 很高
• 热点表问题
  • 某些表在 table_read 中高频出现
• SQL 写法问题
  • 过滤条件不足、返回列太多、Join 顺序不合理、子查询过重
• 执行计划问题
  • 需要重点看 plan、statistics、query_detail、extended_info

---

输出要求

实例级整体慢 Query 诊断文档规范

标题规范

• 实例级分析标题统一为：Hologres 实例级整体慢 Query 诊断
• 不出现"报告"二字

分析人规范

• 分析人字段必须写实际执行诊断 SQL 的 current_user（如 <current_user>）
• 不写固定值如"QoderWork"或"AI助手"

引擎类型分析规范

• digest 聚合和单次最慢 SQL 分析时，必须一并查询并分析 engine_type
• engine_type 字段为数组类型，聚合查询中需使用 engine_type::text 进行转换
• Fixed Plan（FixedQE）类 SQL：以点查/点写为主，性能特征与 HQE 分析型查询不同，在慢 SQL 诊断中无需作为重点分析对象，可简要提及执行频次和总耗时即可
• HQE 类 SQL：为分析型查询主引擎，需重点分析扫描量、内存、CPU、执行计划等
• PQE 类 SQL：说明有部分算子未走 HQE，需判断是否可改写回 HQE
• PG 类 SQL：多为系统表查询或 DDL，ANALYZE 等后台任务走此引擎属正常

实例整体分析输出建议包含

1. 分析时间范围
2. SQL 总量、成功数量、失败数量总结
3. 慢 SQL 总体情况总结
4. TOP 慢 SQL 总结
5. TOP 总耗时 SQL 模板总结
6. 主要用户 / 应用总结
7. 主要涉及表总结
8. 资源瓶颈总结
9. 错误 SQL 总结
10. 优先优化清单总结
11. 每项诊断结果总结
12. 最终优化建议总结

单条 SQL 分析输出建议包含

1. query_id
2. SQL 原文
3. 执行耗时总结
4. 扫描与返回特征总结
5. 资源消耗总结
6. 读写表总结
7. 执行计划摘要总结
8. 慢因总结
9. 优化建议总结

---

输出模板总则

每个诊断项都必须采用以下固定格式输出：

【诊断项名称】
- 指标口径：{统计口径说明}
- 关键结果：{核心数值或Top对象}
- 现象总结：{现象描述}
- 原因判断：{原因分析}
- 建议：{优化建议}
- 结论：{一句话总结}