Hologres Query Optimizer

⚠️ 执行前就绪检查（所有分析步骤之前完成）：

1. 已 pip install hologres-cli，且 hologres status 能连通目标实例（连接哪个实例 / 库由当前 profile 决定，可用 --profile <name> 切换）。
2. export HOLOGRES_SKILL=hologres-query-optimizer，便于事后审计。

完整就绪细节（权限 / GUC 作用域）见 references/preconditions.md。

Hologres Query Execution Plan Analyzer

基于 EXPLAIN / EXPLAIN ANALYZE 与慢查询日志记录分析并优化 Hologres SQL。支持三种输入:query_id、原始 SQL、粘贴的 EXPLAIN ANALYZE 文本。文档目标 Hologres V1.3.4x+。所有 SQL 通过 hologres sql run / hologres sql explain 执行,GUC 通过 hologres guc 操作。

hologres-cli 约定

• 慢日志 / 原始 SQL 查询用 hologres sql run --no-limit-check "<SQL>"。
• 执行计划用 hologres sql explain "<SQL>"(内部执行 EXPLAIN <SQL>)。EXPLAIN ANALYZE 需用 hologres sql run --no-limit-check "EXPLAIN ANALYZE <SQL>"。
• GUC 库级持久化用 hologres guc set <param> <value> / hologres guc reset <param>;查看用 hologres guc show <param> / hologres guc list。
• 连接层已自动 SET hg_computing_resource = 'serverless';来源标记由 export HOLOGRES_SKILL 注入 application_name,无需 手写 SET ... 前缀。
• 输出 query / query_id / plan 必须完整,禁止 用 left() / substr() / ::char(N) 截断。
• 数据库由当前 profile 的 database 决定;换库用 hologres config set database <db> 或 --profile <name>。

Supported Inputs

当用户提供 query_id 时,不要 让用户先贴 SQL/计划 —— 直接查 hologres.hg_query_log。它记录已完成 SQL,字段含 query_id、query、plan、statistics、duration、optimization_cost、start_query_cost、get_next_cost、read_bytes、shuffle_bytes、memory_bytes、cpu_time_ms、engine_type、table_read、query_detail。

EXPLAIN vs EXPLAIN ANALYZE

EXPLAIN SELECT * FROM my_table WHERE id > 100;
EXPLAIN ANALYZE SELECT * FROM my_table WHERE id > 100;

Query ID 工作流

1. 查慢日志记录。完整 SQL、结果处理矩阵、阶段症状映射见 references/slow-log-lookup.md。
2. 若 plan 非空,连同同记录的阶段/资源指标一起分析。
3. 若 plan 为空但 query 存在,跑 EXPLAIN <query>;仅在确认重跑安全后才跑 EXPLAIN ANALYZE。
4. 若查无结果,请用户放宽 query_start 范围或提供 SQL / EXPLAIN ANALYZE 文本。

Reading EXPLAIN Output

自底向上读计划,每个 -> 是一个节点/算子。

Reading EXPLAIN ANALYZE Output

输出四节:Query Plan、ADVICE、Cost、Resource。

Query Plan Metrics

格式:[dop_in:dop_out id=X dop=N time=max/avg/min rows=total(max/avg/min) mem=max/avg/min open=X get_next=Y]

time 累加。当前算子耗时 = 当前 time − 子节点 time。

ADVICE Section

系统自动建议:

• 缺索引:Table xxx misses bitmap index
• 缺统计:Table xxx Miss Stats! please run 'analyze xxx';
• 数据倾斜:shuffle data skew! max rows is X, min rows is Y

Cost Breakdown

Resource Consumption

格式:total(max_worker/avg_worker/min_worker)

Common Operators

详细算子参考:references/operators.md。

Optimization Workflow

1. 判定输入类型:query_id、原始 SQL、粘贴的 EXPLAIN ANALYZE 文本。
2. 对 query_id,先查 hologres.hg_query_log,以记录的 query / plan 为主证据。
3. 对原始 SQL,仅在重跑可接受时跑 EXPLAIN ANALYZE,否则用 EXPLAIN。
4. 检查 ADVICE 找即时修复点。
5. 定位瓶颈算子(减去子节点耗时后 time 最高者)。
6. 施加针对性优化:

Key GUC Parameters

会话级(单次 SQL 内,经 hologres sql run):

SET optimizer_force_multistage_agg = on;
SET optimizer_join_order = 'query';   -- 跟随 SQL 顺序
SET optimizer_join_order = 'greedy';  -- 贪心
SET hg_experimental_enable_cross_join_rewrite = off;

库级持久化(对所有新连接生效,经 hologres guc):

hologres guc set optimizer_force_multistage_agg on
hologres guc set optimizer_join_order query
hologres guc reset optimizer_join_order

完整 GUC 目录:references/guc-parameters.md。

Best Practices

1. 用户提供 query_id 时优先用慢日志记录的证据。
2. 数据大量变化后跑 ANALYZE。
3. 按 JOIN/GROUP BY 模式设计 distribution_key。
4. 范围查询列设 clustering_key。
5. 低基数过滤列用 bitmap 索引。
6. Join 中确保小表做 hash 表。
7. 尽量避免非等值连接。
8. PQE 函数改写为 HQE 替代。
9. 仅在重跑查询安全且预期时,才在生产用 EXPLAIN ANALYZE。

注意事项

1. hologres.hg_query_log 默认保留 30 天、单次最多返回 10000 条;查询必须带 query_start 范围或 query_id 条件,避免全表扫描。
2. 当 hologres sql run 返回空结果(无数据)时,禁止自行改参重试或变通获取;直接跳过该步骤,在输出中标注「无数据」。
3. EXPLAIN ANALYZE 会真正执行查询,生产环境慎用,必要时设 statement_timeout。

References