用途:回答“字典是否已加载、数据是否新鲜、是否值得占用这些内存”,通过查询 system.dictionaries、system.query_log、system.asynchronous_metrics 与 system.text_log 进行诊断。若连接模式、集群和时间窗口尚未确定,需先运行 altinity-expert-clickhouse-connection。
主要能力:查询包 checks.sql 含 15 项检查,覆盖字典清单、健康与加载状态、内存占用对比服务器内存、内存占用最高的字典、配置与 layout、相对 lifetime_max 的时效、当前失败、日志中的加载错误、来自 query_log 的查找性能、命中与未命中比例、cache 字典分析、flat 与 hashed 尺寸检查、源类型、ClickHouse 源字典的连通性以及计划重载状态;其中 1 项需要 system.text_log。reference.md 提供背景(设置、容量规划、反模式),仅在需要解释建议时阅读。
使用方式:从本技能目录读取各查询包文件。一次只运行一条语句,不要整文件运行;语句以 ; 结尾并以 -- @check <id> <title> 头开始,需保留 id 与结果对应。遵守 -- @requires:当指定表缺失、需要 keeper 而服务器无 Keeper/ZooKeeper、或版本条件不满足时跳过该语句,并列出被跳过的 id 及原因。存在 cluster 宏时保留 {cluster} 原样,否则套用连接技能的改写规则;其他 {placeholder} 为模板变量,须先替换为真实值或跳过。出错时记录 check id 与错误首行后继续;仅对 UNKNOWN_IDENTIFIER 执行 DESCRIBE TABLE system.<table> 并去掉缺失列。severity 列是该行的结论,直接采用,不要重新评级。
深查语句:在某个字典被重载后,或需要细看某个字典时,直接读取其加载状态。将 {dictionary_name} 替换为 check dictionaries-02 或 dictionaries-07 中的名称,运行:SELECT database, name, status, loading_start_time, last_successful_update_time, loading_duration, element_count, formatReadableSize(bytes_allocated) AS memory, last_exception FROM clusterAllReplicas('{cluster}', system.dictionaries) WHERE name = '{dictionary_name}'; 解释规则:状态为 FAILED 或 LOADING_FAILED 且 last_exception 非空,属源问题而非 ClickHouse 问题,应引用异常文本;开启 dictionaries_lazy_load 且尚未查询过时,NOT_LOADED 属正常。seconds_since_update 大于 lifetime_max 表示重载逾期或静默失败,大于两倍表示正在提供陈旧数据。bytes_allocated / element_count 超过每键 1000 字节属浪费的 layout;flat layout 用于稀疏或大整数键会按整个键范围分配,应改用 hashed 或 sparse_hashed;工作集仅为超大数据源的小部分时,cache 或 ssd_cache 更省内存。cache 型字典命中率低说明选择错误或容量过小,每次未命中都会同步回源,反而比不用字典更慢。源不可达时应从 ClickHouse 服务器主机检查连通性,DNS、防火墙与凭据均属服务器端。强制重载可由用户执行 SYSTEM RELOAD DICTIONARY 或 SYSTEM RELOAD DICTIONARIES,不要自行执行。字典内存计入服务器总内存预算,且压力下不会回收。
报告格式:头部含连接模式、集群或“single node”、ClickHouse 版本、时间窗口;发现项表格列为 check、severity、object、evidence、recommendation,Critical 优先,证据需引用结果行中的数字;OK 检查用一行列出无问题行的 check id;跳过与失败检查列出 id 及原因或错误首行,此节不可省略;下一步列出后续技能与即时行动。
后续技能:字典内存占 RAM 比例大或查询因内存限制失败,加载 altinity-expert-clickhouse-memory;加载失败需服务器日志完整异常文本,加载 altinity-expert-clickhouse-logs;dictGet 查找慢且主导查询时间,加载 altinity-expert-clickhouse-reporting;ClickHouse 源字典在远端主机或副本失败,加载 altinity-expert-clickhouse-replication;源查询被权限拒绝,加载 altinity-expert-clickhouse-grants;问题范围不明,加载 altinity-expert-clickhouse-overview。