SuperAPI AI 工具集

altinity-expert-clickhouse-schema

数据与分析

查看项目

更新于 10-15 16:48

技能介绍

用途:判断一张 ClickHouse 表是否符合 ClickHouse 期望的设计方式,覆盖分区、ORDER BY 与主键、列数、Nullable 使用、标识符长度、物化视图结构等。若尚未确定连接模式、集群与时间窗口,需先运行 altinity-expert-clickhouse-connection。

主要能力:技能目录内含查询包。checks.sql 含 10 项检查:分区健康审计、collapse 类引擎的超大分区、主键分析、列数、Nullable 列审计、过长的表名与列名、物化视图设计问题、物化视图依赖链、表概览,以及影响上述结果的表级 MergeTree 设置。reference.md 提供设置、容量估算与反模式的背景说明,仅在需要解释建议时查阅。

使用方式:从技能目录读取查询包文件,逐条执行语句,禁止整文件运行。语句以 ; 结尾、以 -- @check <id> <title> 开头,保留 id 与结果对应。遇到 -- @requires 时按条件跳过(表缺失、需要 Keeper/ZooKeeper 而服务端没有、版本条件不满足),并记录跳过的 id 与原因。{cluster} 是集群宏时保持原样,否则套用连接技能的重写规则;其他 {placeholder} 为模板变量,需先替换为真实值。出错时记录 check id 与错误首行后继续;仅对 UNKNOWN_IDENTIFIER 运行 DESCRIBE TABLE system.<table> 并去掉缺失列。severity 列是判定结果,照抄而不重新分级。

判断规则:ORDER BY 首列宜低基数且常被过滤(租户、区域、类型),范围查询常见时第二列用时间;UUID 或哈希作首列、微秒精度 DateTime64 作首列均为反模式。分区粒度经验上每表数十到数百个分区、每个 1-10 GB;约每月 1 TB 以上才值得按天分区。超大分区只对 Replacing、Collapsing、Summing、Aggregating、Graphite 引擎重要,超过 max_bytes_to_merge_at_max_space_in_pool 的分区永远无法合并,解决方法是更细的分区键而非更大 pool。大列压缩比低于 2 通常意味着类型或编码有误。schema-03 为 Minor,只提示首键列像 ID、类型过宽或压缩差,需先用真实查询过滤确认。schema-07 输出 issue 列而非 severity:物化视图中的 JOIN 只在左表插入时触发,右表会静默过期;没有 TO 的物化视图拥有无法独立修改或备份的隐藏 .inner 表。schema-09 与 schema-10 只提供上下文,不应作为问题行列出。

报告格式:表头含连接模式、集群或“单节点”、ClickHouse 版本与时间窗口;findings 表含 check、severity、object、evidence、recommendation,Critical 在前;OK 检查一行列出无问题行的 id;跳过与失败检查必须列 id 与原因或错误首行;最后给出下一步技能与动作。

限制:该技能只做诊断与建议,不自动修改表结构;改变 ORDER BY 意味着重建表。资料未提供具体收费、许可或支持平台信息。