altinity-expert-clickhouse-reporting

查询性能分析

根据 system.query_log、system.processes 和 system.query_views_log 回答“哪些查询速度慢或失败了，原因是什么”。查询按 normalized_query_hash 分组，该字段会折叠字面值，因此每一行代表一种查询模式，而非一次执行。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 15 项检查：当前正在运行的查询、近期性能摘要、最慢的查询、最常见的查询模式、按 CPU 时间统计的查询、读取数据过多的查询、按访问表统计的查询、近期失败及按错误代码汇总的失败、查询类型分布、查询高峰时段、按用户统计的查询、插入期间的物化视图执行情况、按查询统计的物化视图慢查询细分，以及分布式查询性能。其中 2 项需要 system.query_views_log。
• reference.md — 背景信息（设置、容量规划、反模式）；仅在需要解释建议时阅读。

如何运行查询包

1. 从此技能的目录读取每个包文件（技能加载器会打印目录路径）。
2. 每次运行一条语句，切勿运行整个文件。语句以 ; 结束，并以 -- @check <id> <title> 标头开头；将 id 与结果一并保留。
3. 遵循 -- @requires：当指定的表不存在、需要 keeper 但服务器没有 Keeper/ZooKeeper，或版本条件不满足时，跳过该语句。列出跳过的 id 及原因。
4. 如果存在集群宏，按原样保留 {cluster}；否则遵循连接技能的改写规则。其他任何 {placeholder} 都是模板变量：先替换为实际值，否则跳过该语句。
5. 出错时，记录检查 id 和错误的首行，然后继续。仅当错误为 UNKNOWN_IDENTIFIER 时，运行 DESCRIBE TABLE system.<table> 并移除缺失的列。
6. severity 列是该行的判定结果。照录，不要重新评级。

深入分析语句

对于已知 query_id 的某个慢查询，测量索引选择性。SelectedMarks 除以 SelectedMarksTotal，表示主索引未能裁剪的表数据比例：接近 1 意味着 ORDER BY 键没有发挥作用。

SELECT
    query_id,
    read_rows,
    result_rows,
    formatReadableSize(read_bytes) AS read_bytes,
    ProfileEvents['SelectedParts'] AS selected_parts,
    ProfileEvents['SelectedMarks'] AS selected_marks,
    ProfileEvents['SelectedMarksTotal'] AS selected_marks_total,
    round(ProfileEvents['SelectedMarks'] / nullIf(ProfileEvents['SelectedMarksTotal'], 0), 4) AS marks_read_fraction
FROM clusterAllReplicas('{cluster}', system.query_log)
WHERE query_id = '{query_id}' AND type = 'QueryFinish';

然后检查该表是否有可以进一步裁剪数据的数据跳过索引。

SELECT database, table, name AS index_name, type, expr, granularity
FROM clusterAllReplicas('{cluster}', system.data_skipping_indices)
WHERE database = '{database}' AND table = '{table}';

解读规则

• read_rows 远大于 result_rows 表示选择性差，而非服务器速度慢。引用这两个数值，并转交索引分析技能；解决方法是调整 ORDER BY 键或使用跳过索引，而非增加硬件。
• 按 normalized_query_hash 对发现结果分组。一种模式运行 5000 次、每次耗时 200 ms，代价高于一个耗时 60 s 的查询；只有模式视图才能显示这一点。报告查询模式及其总耗时，而非单次最慢的执行。
• 如果同一 normalized_query_hash 反复出现且结果相同，则可能适合使用查询缓存；优化查询本身之前，先检查缓存技能。
• 查询的 memory_usage 较高，说明问题出在聚合或联接，而非扫描。请转交内存技能，而不是建议使用索引。
• 如果查询涉及的分区数较多（SelectedParts 相对于表的分区总数较高），说明读取受合并积压影响。先解决合并问题；查询计划可能已经是最优的。
• reporting-13 和 reporting-14 报告的慢速物化视图会拖慢触发它们的 INSERT，而非 SELECT。此发现应归入数据摄取路径。
• 失败：type IN ('ExceptionBeforeStart', 'ExceptionWhileProcessing') 表示两种不同情况。ExceptionBeforeStart 表示查询从未运行（解析、访问或限制拒绝）；ExceptionWhileProcessing 表示查询运行后失败，通常是触发了内存或超时限制。
• 汇总失败时，忽略本诊断会话自身产生的错误代码（UNKNOWN_IDENTIFIER、UNKNOWN_TABLE、SYNTAX_ERROR）。

报告格式

1. 标题：连接模式、集群或“单节点”、ClickHouse 版本、时间范围。
2. 发现：包含 check、severity、object、evidence、recommendation 列的表格；每项发现一行，按严重程度从高到低排列。证据引用结果行中的数字。
3. 正常检查：用一行列出未返回问题行的检查 ID。
4. 已跳过和失败的检查：检查 ID 及原因或第一条错误信息。此部分绝不可省略。
5. 后续步骤：接下来要加载的技能和立即采取的操作。

后续技能

• read_rows 远高于 result_rows、标记剪枝率低、存在缺失或未使用的跳过索引 → 加载技能 altinity-expert-clickhouse-index-analysis
• 单个查询内存使用量高或出现 MEMORY_LIMIT_EXCEEDED 故障 → 加载技能 altinity-expert-clickhouse-memory
• 查询每张表读取的 part 数量很多 → 加载技能 altinity-expert-clickhouse-merges
• 重复的相同查询、标记缓存或未压缩缓存命中率低 → 加载技能 altinity-expert-clickhouse-caches
• 插入期间物化视图速度缓慢 → 加载技能 altinity-expert-clickhouse-ingestion
• ORDER BY、分区或物化视图设计看起来不合理 → 加载技能 altinity-expert-clickhouse-schema
• 分布式查询耗时超过各分片耗时之和，或某个副本出现延迟 → 加载技能 altinity-expert-clickhouse-replication
• 错误代码中出现 ACCESS_DENIED 或身份验证失败 → 加载技能 altinity-expert-clickhouse-grants
• 查询延迟与磁盘读取吞吐量相关 → 加载技能 altinity-expert-clickhouse-storage