用途:回答“为什么这个变更卡住或很慢”,针对 ClickHouse 的 ALTER UPDATE、ALTER DELETE、MATERIALIZE 以及列变更进行诊断。注意变更会后台重写整个 part,并非事务性的行更新。若连接模式、集群和时间窗口尚未确定,应先运行 altinity-expert-clickhouse-connection。
主要能力:查询包 checks.sql 含 11 项检查,包括当前变更状态、按表变更汇总、按年龄检测卡住变更、最近完成的变更、各表变更耗时、part 日志中的失败变更、正在执行的变更、仍在等待变更的 part、变更与 merge 对后台池的竞争、变更创建速率及按命令类型细分;其中 3 项依赖 system.part_log。reference.md 提供设置、容量与反模式背景。识别卡住变更后,可用三条深挖语句查看同表竞争的 merge、复制队列以及各 part 的 data_version。
判定规则:某表待处理变更超过 10 个、变更超过一小时未完成、latest_fail_reason 非空,三者任一即为发现项,需引用 mutation_id、年龄和失败原因。latest_fail_reason 非空且 num_tries 上升说明在重试而非推进,需先读异常文本。频繁的小 ALTER UPDATE 是队列增长的常见原因;无 WHERE 或匹配大多数行的 ALTER DELETE 会重写全表,建议改用 TTL 或 DROP PARTITION。同表并发变更会串行并挤占 merge,建议逐条执行。
使用方式:从技能目录读取查询包,逐条执行语句而非整文件;保留 -- @check <id> <title> 头部与 id;遵守 -- @requires,缺表或缺 Keeper 或版本不符时跳过并说明原因。{cluster} 按连接技能规则处理。出错时记录 check id 与错误首行后继续;遇 UNKNOWN_IDENTIFIER 执行 DESCRIBE TABLE system.<table> 并去掉缺失列。severity 列即该行结论,照抄即可。
限制:取消卡住变更可由用户执行 KILL MUTATION(需指定数据库、表与 mutation_id),本技能不代为执行;被终止的变更会使表部分变更且无自动回滚。system.part_log 关闭时相关检查跳过,变更耗时与历史失败将不可知,应如实说明而非报告变更已正常完成。报告需包含表头、发现项表格、OK 检查、跳过与失败检查、后续步骤。