clickhouse-best-practices

ClickHouse 最佳实践

涵盖 ClickHouse 的全面指南，包括架构设计、查询优化、数据写入和 AI Agent 连接。包含 4 个主要类别（架构、查询、插入、Agent）中的 31 条规则，并按影响程度排序。

官方文档： ClickHouse 最佳实践

重要：如何应用此技能

回答 ClickHouse 问题之前，请按以下优先级执行：

1. 检查 rules/ 目录中是否有适用规则
2. 如果有规则： 应用规则，并在回答中引用，使用“根据 rule-name……”
3. 如果没有规则： 使用大模型掌握的 ClickHouse 知识或搜索文档
4. 如果不确定： 使用网页搜索查找当前最佳实践
5. 始终注明来源： 规则名称、“ClickHouse 通用指南”或 URL

规则优先的原因： ClickHouse 有一些特定行为（列式存储、稀疏索引、合并树机制），通用数据库经验可能会产生误导。这些规则汇总了经过验证的 ClickHouse 专属指导。

---

Agent 连接与查询工作流

查询 ClickHouse 之前，Agent 必须建立连接并遵循发现工作流：

1. rules/agent-connect-mcp.md - 连接设置（MCP + CLI）、凭据发现、输出格式选择
2. rules/agent-discovery-schema.md - 关键： 7 步架构发现工作流
3. rules/agent-query-safety.md - 关键： LIMIT、超时、渐进式探索

每次 Agent 会话都应遵循以下顺序：

1. 连接 — 通过 MCP 或 CLI 建立连接（参见 agent-connect-mcp）
2. 发现 — 数据库 → 表 → 列 + 注释 → 排序键 → 跳过索引 → 样本 → EXPLAIN
3. 规划 — 利用排序键和跳过索引知识编写高效的 WHERE 子句
4. 执行 — 使用 LIMIT 和超时运行查询
5. 恢复 — 遇到超时或内存错误时，缩小筛选范围并重试（参见 agent-query-safety）

子 Agent 架构说明

如果你的系统会将 ClickHouse 任务分派给专用子 Agent：

• 架构发现 + 查询执行： 任何模型均可——这些步骤是程序性的
• EXPLAIN 分析 + 查询优化： 使用中档推理能力的模型效果更好
• 根据全部 28 条规则审查架构设计： 使用中档推理能力的模型效果更好

---

审查流程

架构审查（CREATE TABLE、ALTER TABLE）

按顺序阅读以下规则文件：

1. rules/schema-pk-plan-before-creation.md - ORDER BY 不可变
2. rules/schema-pk-cardinality-order.md - 键中的列顺序
3. rules/schema-pk-prioritize-filters.md - 筛选列的纳入
4. rules/schema-types-native-types.md - 正确选择类型
5. rules/schema-types-minimize-bitwidth.md - 数值类型大小
6. rules/schema-types-lowcardinality.md - LowCardinality 的用法
7. rules/schema-types-avoid-nullable.md - Nullable 与 DEFAULT
8. rules/schema-partition-low-cardinality.md - 分区数量限制
9. rules/schema-partition-lifecycle.md - 分区用途

检查以下内容：

• PRIMARY KEY / ORDER BY 列顺序（基数由低到高）
• 数据类型与实际数据范围相符
• 在适当的字符串列上使用 LowCardinality
• 分区键基数有上限（100-1,000 个值）
• 使用 ReplacingMergeTree 时包含版本列

查询审查（SELECT、JOIN、聚合）

阅读以下规则文件：

1. rules/query-join-choose-algorithm.md - 算法选择
2. rules/query-join-filter-before.md - 连接前筛选
3. rules/query-join-use-any.md - ANY 与常规 JOIN 的选择
4. rules/query-index-skipping-indices.md - 二级索引的使用
5. rules/schema-pk-filter-on-orderby.md - 筛选条件与 ORDER BY 的对齐

检查以下内容：

• 筛选条件使用 ORDER BY 前缀列
• JOIN 前先筛选表（而不是 JOIN 后）
• 根据表大小选择正确的 JOIN 算法
• 为非 ORDER BY 筛选列使用跳过索引

用于插入策略审查（数据摄取、更新、删除）

阅读以下规则文件：

1. rules/insert-batch-size.md - 批次大小要求
2. rules/insert-mutation-avoid-update.md - UPDATE 的替代方案
3. rules/insert-mutation-avoid-delete.md - DELETE 的替代方案
4. rules/insert-async-small-batches.md - 异步插入用法
5. rules/insert-optimize-avoid-final.md - OPTIMIZE TABLE 的风险

检查以下事项：

• 每次 INSERT 的批次大小为 10K-100K 行
• 频繁更改时不使用 ALTER TABLE UPDATE
• 更新模式使用 ReplacingMergeTree 或 CollapsingMergeTree
• 高频小批次场景启用异步插入

---

输出格式

请按以下格式组织回复：

## Rules Checked
- `rule-name-1` - Compliant / Violation found
- `rule-name-2` - Compliant / Violation found
...

## Findings

### Violations
- **`rule-name`**: Description of the issue
  - Current: [what the code does]
  - Required: [what it should do]
  - Fix: [specific correction]

### Compliant
- `rule-name`: Brief note on why it's correct

## Recommendations
[Prioritized list of changes, citing rules]

---

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数量
1	主键选择	CRITICAL	schema-pk-	4
2	数据类型选择	CRITICAL	schema-types-	5
3	JOIN 优化	CRITICAL	query-join-	5
4	插入批处理	CRITICAL	insert-batch-	1
5	避免变更操作	CRITICAL	insert-mutation-	2
6	分区策略	HIGH	schema-partition-	4
7	跳数索引	HIGH	query-index-	1
8	物化视图	HIGH	query-mv-	2
9	异步插入	HIGH	insert-async-	2
10	避免 OPTIMIZE	HIGH	insert-optimize-	1
11	JSON 用法	MEDIUM	schema-json-	1
12	Agent 架构发现	CRITICAL	agent-discovery-	1
13	Agent 查询安全性	CRITICAL	agent-query-	1
14	Agent 连接与格式	HIGH	agent-connect-	1

---

快速参考

架构设计 - 主键（CRITICAL）

• schema-pk-plan-before-creation - 创建表之前规划 ORDER BY（不可更改）
• schema-pk-cardinality-order - 按基数从低到高排列列
• schema-pk-prioritize-filters - 纳入经常用于筛选的列
• schema-pk-filter-on-orderby - 查询筛选条件必须使用 ORDER BY 前缀

架构设计 - 数据类型（CRITICAL）

• schema-types-native-types - 使用原生类型，不要所有内容都使用 String
• schema-types-minimize-bitwidth - 使用能够容纳数据的最小数值类型
• schema-types-lowcardinality - 对唯一字符串少于 10K 的列使用 LowCardinality
• schema-types-enum - 对有限值集合使用 Enum 并进行验证
• schema-types-avoid-nullable - 避免 Nullable；改用 DEFAULT

架构设计 - 分区（HIGH）

• schema-partition-low-cardinality - 将分区数量控制在 100-1,000
• schema-partition-lifecycle - 将分区用于数据生命周期管理，而非查询
• schema-partition-query-tradeoffs - 了解分区裁剪的权衡
• schema-partition-start-without - 考虑从不分区开始

架构设计 - JSON（MEDIUM）

• schema-json-when-to-use - 动态架构使用 JSON；已知字段使用类型化列

查询优化 - JOIN（CRITICAL）

• query-join-choose-algorithm - 根据表大小选择算法
• query-join-use-any - 只需一个匹配项时使用 ANY JOIN
• query-join-filter-before - JOIN 前筛选表
• query-join-consider-alternatives - 权衡字典/反规范化与 JOIN
• query-join-null-handling - 使用 join_use_nulls=0 获取默认值

查询优化 - 索引（HIGH）

• query-index-skipping-indices - 对非 ORDER BY 筛选条件使用跳数索引

查询优化 - 物化视图（HIGH）

• query-mv-incremental - 使用增量 MV 实现实时聚合
• query-mv-refreshable - 使用可刷新的 MV 处理复杂 JOIN

插入策略 - 批处理（CRITICAL）

• insert-batch-size - 每次 INSERT 批处理 10K-100K 行

插入策略 - 异步（HIGH）

• insert-async-small-batches - 高频小批次使用异步插入
• insert-format-native - 使用 Native 格式以获得最佳性能

插入策略 - 变更（CRITICAL）

• insert-mutation-avoid-update - 使用 ReplacingMergeTree 代替 ALTER UPDATE
• insert-mutation-avoid-delete - 使用轻量级 DELETE 或 DROP PARTITION

插入策略 - 优化（HIGH）

• insert-optimize-avoid-final - 让后台合并发挥作用

Agent 集成 - 发现（CRITICAL）

• agent-discovery-schema - 查询前始终先发现架构

Agent 集成 - 安全（CRITICAL）

• agent-query-safety - 使用 LIMIT、超时和渐进式探索

Agent 集成 - 连接 + 格式（HIGH）

• agent-connect-mcp - MCP + CLI 设置、凭据发现和输出格式选择

---

何时应用

遇到以下情况时，此技能会启用：

• AI Agent 连接到 ClickHouse（MCP、CLI、HTTP）

• ClickHouse 的 Agent 工作流设计

• 架构发现或探索请求

• CREATE TABLE 语句

• ALTER TABLE 修改

• 关于 ORDER BY 或 PRIMARY KEY 的讨论

• 数据类型选择问题

• 慢查询排查

• JOIN 优化请求

• 数据导入管道设计

• 更新/删除策略问题

• ReplacingMergeTree 或其他专用引擎的用法

• 分区策略决策

---

规则文件结构

rules/ 中的每个规则文件都包含：

• YAML frontmatter：标题、影响级别、标签
• 简要说明：此规则的重要性
• 错误示例：反模式及其说明
• 正确示例：最佳实践及其说明
• 补充背景：权衡、适用场景和参考资料

---

完整编译文档

如需查看所有规则展开后的完整指南：AGENTS.md

如果需要快速检查多条规则，而无需阅读单个文件，请使用 AGENTS.md。