altinity-expert-clickhouse-schema

表结构和设计分析

根据 system.parts、system.tables、system.columns、system.parts_columns、system.data_skipping_indices 和 system.merge_tree_settings，回答“这张表的设计是否符合 ClickHouse 的要求”。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• checks.sql — 10 项检查：分区健康状况审计、折叠引擎上的超大分区、主键分析、列数量、Nullable 列审计、过长的表名和列名、物化视图设计问题、物化视图依赖链、表概览，以及影响上述所有方面的表级 MergeTree 设置。
• 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 列是该行的判定结果。照原样复制，不要重新评级。

深入分析语句

针对单张表的分区分布，用于判断分区键是否过于细化。

SELECT
    partition,
    count() AS parts,
    sum(rows) AS total_rows,
    formatReadableSize(sum(bytes_on_disk)) AS partition_size
FROM clusterAllReplicas('{cluster}', system.parts)
WHERE active AND database = '{database}' AND table = '{table}'
GROUP BY partition
ORDER BY partition DESC
LIMIT 100;

针对单张表的列压缩，用于找出类型或编解码器不正确的列。

SELECT
    name, type, compression_codec,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed,
    formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed,
    round(sum(data_uncompressed_bytes) / nullIf(sum(data_compressed_bytes), 0), 2) AS ratio
FROM clusterAllReplicas('{cluster}', system.columns)
WHERE database = '{database}' AND table = '{table}'
GROUP BY name, type, compression_codec
ORDER BY sum(data_compressed_bytes) DESC
LIMIT 50;

一个数据库中声明的数据跳过索引。

SELECT database, table, name AS index_name, type, expr, granularity
FROM clusterAllReplicas('{cluster}', system.data_skipping_indices)
WHERE database = '{database}'
ORDER BY database, table;

解读规则

• ORDER BY 指南：第一列应基数低且经常用于筛选（租户、区域、类型）；如果常见范围查询，第二列应基于时间；其余筛选列按选择性排序，选择性最高的放最后。将 UUID 或哈希值作为第一列是反模式；将微秒精度的 DateTime64 放在第一列也是如此，因为每一行的值都不同，稀疏索引无法裁剪数据。
• 分区粒度经验法则：每张表以几十到几百个分区为目标，每个分区大小为 1-10 GB。只有每月数据量大约超过 1 TB 时，才有理由按天分区；低于此规模时，通常应按月分区或不分区。Check schema-01 会对此评分；引用其中的分区大小中位数作为证据。
• 超大分区（schema-02）只对 Replacing、Collapsing、Summing、Aggregating 和 Graphite 引擎有影响。大于 max_bytes_to_merge_at_max_space_in_pool 的分区永远无法合并为一个 part，因此去重或聚合永远无法完成。解决方法是使用更细的分区键，而不是增大内存池。
• 大型列的压缩率低于 2，意味着类型或编解码器不合适。重复性较强的字符串应改为 LowCardinality(String)；连续整数和时间戳在使用 ZSTD 前，适合先应用 Delta 或 DoubleDelta。
• Check schema-03 按设计属于 Minor：它只会标记看起来像 ID、类型较宽或压缩效果不佳的首个键列。请先根据实际查询筛选条件确认，因为更改 ORDER BY 意味着要重建表。
• Check schema-07 输出的是 issue 列，而非 severity。物化视图中的 JOIN 只会在左表插入数据时触发，因此右表会在无提示的情况下变得陈旧。没有 TO 的物化视图会拥有一个隐藏的 .inner 表，无法单独修改或备份。
• Checks schema-09 和 schema-10 返回的是上下文，而非发现项。用它们解释其他结果；不要将其行列为问题。

报告格式

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

后续技能

• 小型或频繁插入导致大量小分区 → 加载技能 altinity-expert-clickhouse-ingestion
• 超大分区、合并积压或每个分区包含大量 parts → 加载技能 altinity-expert-clickhouse-merges
• 主键过宽、占用 RAM，或标记缓存压力过高 → 加载技能 altinity-expert-clickhouse-memory
• 使用此 ORDER BY 的查询扫描行数远多于返回行数 → 加载技能 altinity-expert-clickhouse-index-analysis
• 物化视图在查询时速度缓慢 → 加载技能 altinity-expert-clickhouse-reporting
• 通过 ALTER UPDATE 或 ALTER DELETE 发出的架构变更卡住 → 加载技能 altinity-expert-clickhouse-mutations