altinity-expert-clickhouse-caches

缓存分析与调优

根据 system.metrics、system.asynchronous_metrics、system.events、system.parts、system.server_settings 和 system.metric_log，回答“缓存大小是否合适，是否发挥了作用？”。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 12 项检查：标记缓存健康状况（命中率和 RAM 占比）、未压缩缓存健康状况、查询缓存、编译表达式缓存、每个表的标记字节数、每个表的主键内存占用、随时间变化的缓存事件、当前缓存服务器设置、标记缓存大小分析、对今天查询过的表进行命中率诊断、持有过多标记的表，以及过去一小时逐分钟的标记缓存命中率。检查 caches-07 需要 system.asynchronous_metric_log，caches-12 需要 system.metric_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 列是该行的判定结果。直接复制，不要重新评级。

解读规则

• caches-01 和 caches-02 返回两个判定列：hit_severity 和 size_severity。请同时复制这两列；缓存大小合适也可能毫无用处，缓存有效也可能仍然过大。
• 标记缓存命中率低于 0.7 时为 Moderate，低于 0.5 时为 Major，低于 0.3 时为 Critical。原因依次为：缓存对于工作集来说太小、查询涉及许多不同的表，或工作负载是针对冷数据的许多小查询。调整大小前，使用 caches-10 区分这些情况。
• 标记缓存超过 RAM 的 15 percent 即应报告问题，即使命中率完美也一样。按以下顺序解决原因：提高 caches-11 中相关表的 index_granularity，让合并操作减少过小的部件，删除未使用的表，最后才降低 mark_cache_size。切勿通过降低 index_granularity 来缩小缓存；更小的粒度会产生更多标记，而非更少。
• caches-09 给出目标：理想标记缓存大小为 min（磁盘上的总标记数，RAM 的 15 percent）。如果总标记数已经超过该值，缓存就无法容纳工作集，问题出在架构上。
• 未压缩缓存命中率接近零且未命中很多时，判定为 Moderate，而非 Critical。将大小设为 0（禁用）是合理的生产选择；只有对每个查询或配置文件启用 use_uncompressed_cache 时，缓存才会对重复的小型点读操作有帮助。
• caches-08 只列出服务器设置。mark_cache_size 和 uncompressed_cache_size 是服务器设置；查询缓存大小位于服务器配置中的 <query_cache><max_size_in_bytes>，因此可能不会出现在结果中。use_query_cache 和 use_uncompressed_cache 是查询级设置，不会出现在此处。
• 如果查询缓存未命中主要由非确定性查询或仅运行一次的查询造成，这是预期情况。查询缓存只对相同、重复且确定性的查询有帮助。
• caches-06 中的主键内存不是缓存，无法逐出。请将其与缓存大小分析分开报告。

深入分析语句

查看一个数据库中每张表的标记数量，以找出哪些内容占用了标记缓存：

SELECT table, count() AS parts, sum(marks) AS marks, formatReadableSize(sum(marks_bytes)) AS marks_size, formatReadableSize(sum(bytes_on_disk)) AS data_size FROM system.parts WHERE active AND database = '{database}' GROUP BY table ORDER BY sum(marks_bytes) DESC LIMIT 20;

查看一张表实际生效的 index_granularity，以便在建议更改前进行确认：

SELECT database, table, engine, create_table_query FROM system.tables WHERE database = '{database}' AND name = '{table}';

查看最大的查询缓存条目，以便在 caches-03 显示缓存已满时进行排查：

SELECT substring(query, 1, 120) AS query_preview, formatReadableSize(result_size) AS result_size, stale, shared, expires_at FROM system.query_cache ORDER BY result_size DESC LIMIT 20;

报告格式

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

后续技能

• 缓存占用总 RAM 的很大一部分，或服务接近内存上限 → 加载技能 altinity-expert-clickhouse-memory
• 命中率低且磁盘读取 IO 高 → 加载技能 altinity-expert-clickhouse-storage
• index_granularity 过小或 ORDER BY 范围过宽导致标记过多 → 加载技能 altinity-expert-clickhouse-schema
• 大量微小数据分区导致标记数量膨胀 → 加载技能 altinity-expert-clickhouse-merges
• 查询缓存未命中或昂贵查询重复执行 → 加载技能 altinity-expert-clickhouse-reporting