altinity-expert-clickhouse-mutations

变更跟踪与分析

通过查询 system.mutations、system.merges、system.parts、system.replication_queue 和 system.part_log，回答“为什么此变更卡住或运行缓慢”。变更会在后台重写整个分区，而不是事务性地更新行。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 11 项检查：当前变更状态、按表汇总变更、按等待时长检测卡住的变更、最近完成的变更、按表统计变更时长、part 日志中的失败变更、当前正在执行的变更、仍在等待变更的分区、变更与合并对后台池的竞争、变更创建速率，以及按变更命令类型细分。 其中 3 项需要 system.part_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 列是该行的判定结果。照原样复制；不要重新评定。

深入排查语句

确定某个变更卡住后，以下三条语句可说明阻塞原因。将 {database} 和 {table} 替换为检查 mutations-03 中的表。

与同一张表竞争的合并，因为变更无法在正在合并的分区上启动。

SELECT hostName() AS host, database, table, is_mutation, elapsed, progress, num_parts, result_part_name
FROM clusterAllReplicas('{cluster}', system.merges)
WHERE database = '{database}' AND table = '{table}';

同一张表的复制队列，因为在复制表上，变更是一个可能无限重试的队列条目。

SELECT hostName() AS host, type, create_time, is_currently_executing, num_tries, last_exception
FROM clusterAllReplicas('{cluster}', system.replication_queue)
WHERE database = '{database}' AND table = '{table}'
ORDER BY create_time
LIMIT 20;

按分区查看变更版本。data_version 表示分区已应用到的变更版本，因此值分散意味着只有部分分区应用了该变更。

SELECT hostName() AS host, name, active, level, data_version, modification_time
FROM clusterAllReplicas('{cluster}', system.parts)
WHERE database = '{database}' AND table = '{table}' AND active
ORDER BY data_version DESC, modification_time DESC
LIMIT 30;

解释规则

• 以下情况均视为发现：表上有超过 10 个待处理变更、有变更已持续超过一小时，或 latest_fail_reason 非空。任一情况都足够；引用 mutation_id、持续时间和失败原因作为证据。
• 如果 latest_fail_reason 非空且 num_tries 持续增加，说明变更在重试，而非取得进展。先查看异常文本：内存限制、缺少列和类型错误需要不同的修复方案，而且变更不会自行成功。
• 频繁执行小规模 ALTER UPDATE 语句是队列不断增长的常见原因。每条语句都会创建一个变更，重写所有匹配的数据分区。建议将多行更新批量合并为一个变更，或改用 ReplacingMergeTree 或 CollapsingMergeTree 模型，将更新转为插入。
• 不带 WHERE 子句或匹配大部分行的 ALTER DELETE 会重写整张表。建议改用 TTL 或 DROP PARTITION；相比之下，这两种操作在元数据层面完成，几乎瞬间即可结束。
• 同一张表上的多个并发变更仍会串行执行，并且会挤占合并任务的资源（检查 mutations-09）。建议逐个执行，而不是并行发起。
• 若要取消卡住的变更，用户可以运行 KILL MUTATION，并在 WHERE 子句中指定数据库、表以及来自 check mutations-01 的 mutation_id。不要代为运行。变更被终止后，表会处于部分变更状态：部分数据分区包含新数据，部分则没有，且不会自动回滚。
• 如果 @requires table:system.part_log 标记的检查被跳过，说明 part_log 已禁用。没有它，就无法确定变更耗时和以往的失败情况；应如实说明，而不是报告变更已顺利完成。

报告格式

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

后续技能

• 变更被正在进行的合并阻塞，或后台线程池已饱和 → 加载技能 altinity-expert-clickhouse-merges
• 变更因 MEMORY_LIMIT_EXCEEDED 失败，或峰值内存过高 → 加载技能 altinity-expert-clickhouse-memory
• 大数据分区上的变更速度缓慢，且磁盘或 IO 饱和 → 加载技能 altinity-expert-clickhouse-storage
• 变更卡在复制队列中，或只应用于一个副本 → 加载技能 altinity-expert-clickhouse-replication
• 频繁更新表明应改用 Replacing 或 Collapsing → 加载技能 altinity-expert-clickhouse-schema
• 变更异常需要查看完整服务器日志文本 → 加载技能 altinity-expert-clickhouse-logs