altinity-expert-clickhouse-dictionaries

字典诊断

通过 system.dictionaries、system.query_log、system.asynchronous_metrics 和 system.text_log 回答“字典是否已加载、是否保持最新，以及是否值得占用其消耗的 RAM”。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 15 项检查：字典清单、健康状况和加载状态、相对于服务器 RAM 的内存用量、内存占用最多的字典、配置和布局、相对于 lifetime_max 的过期情况、当前故障、日志中的加载错误、来自 query_log 的查询性能、命中率和未命中率、缓存字典分析、扁平和哈希大小检查、源类型、ClickHouse 源字典的源连接状态，以及计划重新加载状态。其中 1 项需要 system.text_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 列是该行的判定结果。照原样复制；不要重新评级。

深入检查语句

重新加载某个字典后，或需要深入检查某个字典时，直接读取其加载状态。将 {dictionary_name} 替换为检查 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，说明重新加载已逾期或在静默失败。大于 lifetime_max 的两倍，说明字典正在提供过期数据，且重新加载已失败一段时间；结合 dictionaries-08 中的加载错误，查明具体原因。
• bytes_allocated / element_count 超过每个键 1000 字节，说明布局浪费空间。对稀疏键或高整数键使用 flat 布局时，会为整个键范围分配空间；请改用 hashed 或 sparse_hashed。如果工作集只是超大数据源中的一小部分，使用 cache 或 ssd_cache 布局比全部载入内存更省资源。
• 命中率较低的缓存类型字典（dictionaries-10、dictionaries-11）说明选择了错误的类型或缓存空间太小。每次未命中都会同步往返访问数据源，因此低命中率会让查询比完全不使用字典还慢。请增大缓存，或改用能容纳全部数据的 hashed 布局。
• 如果无法访问数据源，请从 ClickHouse 服务所在主机检查连接，而不是从运行本次会话的机器检查。字典数据源由服务端解析：DNS、防火墙规则和凭据都属于服务端；某个数据源在笔记本电脑上能正常工作，在服务端上仍可能失败。
• 用户可以运行 SYSTEM RELOAD DICTIONARY 重新加载一个字典，或运行 SYSTEM RELOAD DICTIONARIES 重新加载所有字典。不要自行运行这些命令：大型字典的重新加载会阻塞查询并重新读取整个数据源，而一次性重新加载所有字典可能导致繁忙的服务端内存激增。
• 字典内存计入服务端总内存预算，内存压力下不会回收。dictionaries-03 显示字典占 RAM 的百分比达到两位数时，无论 max_server_memory_usage 如何设置，这部分内存都无法供查询使用。

报告格式

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

后续技能

• 字典占用大量 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