altinity-expert-clickhouse-merges

合并健康状况与分区积压

根据 system.merges、system.part_log 和 system.parts，回答“合并是否在运行、涉及哪些表、又是什么在阻碍合并？”。如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 8 项检查：当前合并活动及其内存、算法和类型（merges-01）；每台主机和整个集群的活动合并内存（merges-02、merges-03）；按小时统计的合并成功/失败趋势（merges-04）；表级合并判定（merges-05）；合并原因和算法矩阵（merges-06）；每张表的合并 RAM 峰值（merges-07）；分区数量异常表（merges-08）。检查 merges-04 至 merges-07 需要 system.part_log。
• reference.md — 背景信息（合并和 TTL 设置、临时查询保护措施）；仅在需要解释建议时阅读。

如何运行查询包

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 列是该行的判定结果。照原样复制，不要重新评级。

解读规则

按 id 顺序运行检查：先检查当前合并（merges-01），再检查历史趋势（merges-04），然后检查表级判定（merges-05），再检查原因和算法（merges-06），接着检查当前和峰值 RAM（merges-02、merges-03、merges-07），最后检查分区数量异常表（merges-08）。

• 报告结尾必须且只能给出一个判定：PROVED（时间窗口内任何地方都没有成功合并）、DECLINED（整个集群的合并都在成功进行）或 PARTIAL（部分特定表受到阻碍，但其他表仍在合并）。
• 如果同一时间窗口内任何表有成功合并，判定应为 PARTIAL 或 DECLINED，绝不能判为全局合并停止。
• 如果某张表的 merge_ok = 0 且反复出现 MEMORY_LIMIT_EXCEEDED，这是表级阻塞，不是集群级阻塞。
• 如果合并有 100 percent 是 Horizontal，应说明规划器选择了水平合并。除非合并树设置能证明，否则不要声称垂直算法已被禁用。
• 如果 merges-08 中分区数量最多的表来自 system.* 表，应指出告警来源不匹配，避免将问题错误归因于业务表。
• merges-07 的 RAM 峰值是历史数据：当前没有合并但峰值很高，说明问题之前发生过，而不是正在发生。
• 如果缺少 system.part_log，则跳过 merges-04 至 merges-07，因此无法证实集群范围内的合并停止。应说明“没有 part_log，无法证实”，而不是选择一个判定。

有证据支持时，值得指出的结构性原因：

• 单个热点分区（partition_id = 'all'）会导致每次合并都重新读取整张表；建议按时间分区。
• 热点写入表上的繁重 TTL ... GROUP BY ... SET ... 会使合并串行执行；将汇总操作移到物化视图或批处理表，并让基表的 TTL 仅执行删除。
• 反复出现的大型水平合并因 OOM 失败，问题指向行宽和分区大小，而非池容量。
• 分区持续增长但合并正常，说明插入速度超过合并速度：应调整插入批次大小和频率，而不是合并设置。

深入分析语句

过去一小时内某个表的插入与合并速率。net_reduction 连续数分钟为负，意味着插入速度超过合并速度。

SELECT
    toStartOfMinute(event_time) AS minute,
    countIf(event_type = 'NewPart') AS new_parts,
    countIf(event_type = 'MergeParts') AS merges,
    countIf(event_type = 'MergeParts') - countIf(event_type = 'NewPart') AS net_reduction
FROM system.part_log
WHERE database = '{database}'
  AND table = '{table}'
  AND event_time > now() - INTERVAL 1 HOUR
GROUP BY minute
ORDER BY minute DESC
LIMIT 60;

报告格式

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

在“发现”部分的第一行注明 PROVED/DECLINED/PARTIAL 判定。

后续技能

• 合并因 MEMORY_LIMIT_EXCEEDED 失败，或峰值合并 RAM 接近限制 → 加载技能 altinity-expert-clickhouse-memory
• 磁盘吞吐正常但合并缓慢，或分区和 ORDER BY 看起来不合理 → 加载技能 altinity-expert-clickhouse-schema
• 磁盘 IO 较高或磁盘已满，导致合并缓慢 → 加载技能 altinity-expert-clickhouse-storage
• 合并队列被 mutations 阻塞，或出现 MutatePart 错误 → 加载技能 altinity-expert-clickhouse-mutations
• 合并问题同时伴随复制延迟或复制队列不断增长 → 加载技能 altinity-expert-clickhouse-replication
• 如果主要原因是分区创建速率，而不是合并能力 → 加载技能 altinity-expert-clickhouse-ingestion
• 需要详细的分区历史记录 → 加载技能 altinity-expert-clickhouse-part-log