前言¶

在 Agent 裏問 ClickHouse 建表、改查詢或調配置，模型往往會套用通用 OLTP 直覺：隨便 Nullable、大分區、JOIN 後再過濾。列存、稀疏索引和 MergeTree 的機制不同，這類建議輕則浪費存儲，重則拖垮查詢。下面介紹 ClickHouse 官方維護的 Agent Skill clickhouse-best-practices：在給出 schema、查詢或配置相關建議之前，必須先對照內置規則覈對，並在回覆裏引用具體規則名。

這是什麼¶

clickhouse-best-practices 是 ClickHouse Agent Skills 倉庫中的一個 Skill，由 ClickHouse Inc 維護，許可證 Apache-2.0，當前元數據版本爲 0.4.0。Skill 描述寫明：審查 ClickHouse schema、查詢或配置時必須使用；內含 31 條須在給出建議前檢查的規則，覆蓋 schema 設計、查詢優化、數據寫入與 Agent 連通四類，並按影響優先級排序。規則與官方文檔 ClickHouse Best Practices 對齊，屬於「可執行的檢查清單 + 引用格式」，而不是替代 ClickHouse 文檔本身。

同倉庫還提供架構顧問、Node 客戶端排障、chdb、基礎設施等其它 Skill；本篇只圍繞 best-practices 這一條。

核心功能¶

規則優先的回答流程¶

回答任何 ClickHouse 相關問題前，Skill 要求按以下順序處理：

1. 在 rules/ 目錄中查找適用規則；
2. 若存在適用規則：按規則執行，並在回覆中用 Per \rule-name`…` 形式引用；
3. 若無對應規則：再用模型自帶的 ClickHouse 知識或查文檔；
4. 仍不確定時：用 Web 搜索當前最佳實踐；
5. 始終標明來源：規則名、「general ClickHouse guidance」或 URL。

這樣做的原因是：列存、稀疏索引、MergeTree 合併等行爲與常見數據庫直覺不一致，規則裏編碼的是經校驗的 ClickHouse 專用指導。

四類審查與 Agent 工作流¶

Schema 審查（CREATE TABLE / ALTER TABLE）：按固定順序閱讀主鍵規劃、基數排序、過濾列、類型、LowCardinality、Nullable、分區等規則文件，並覈對 ORDER BY 不可變、分區基數約 100–1,000、ReplacingMergeTree 是否帶版本列等檢查項。

查詢審查（SELECT / JOIN / 聚合）：覆蓋 JOIN 算法選擇、JOIN 前過濾、ANY JOIN、跳數索引、WHERE 與 ORDER BY 對齊等。

寫入策略審查：批量大小（建議每批約 10K–100K 行）、避免頻繁 ALTER TABLE UPDATE/DELETE、異步小批量寫入、慎用 OPTIMIZE TABLE 等。

Agent 連通與查詢：連接（MCP + CLI）、7 步 schema 發現、帶 LIMIT 與超時的安全查詢；推薦會話順序爲 Connect → Discover → Plan → Execute → Recover。

規則分類與優先級（節選）¶

規則文件命名示例：schema-pk-plan-before-creation（建表前規劃 ORDER BY，因其不可變）、query-join-filter-before（JOIN 前先過濾）、insert-batch-size（批量寫入大小）等，完整列表見倉庫內 SKILL.md 與 rules/。

規定的輸出結構¶

做審查類回覆時，Skill 要求 Agent 按模板組織結果，便於對照合規與違規項：

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

## Findings
### Violations
- **`rule-name`**: ...
### Compliant
- `rule-name`: ...

## Recommendations
...

安裝與啓用¶

Skill 隨 clickhouse/agent-skills 整包分發，可用官方文檔中的兩種方式安裝到已支持的 Agent 環境：

npx skills add clickhouse/agent-skills

npx skills 會檢測本機已安裝的 Agent 並提示選擇安裝目標。若已安裝 clickhousectl，也可執行：

clickhousectl skills

Skill 遵循 agentskills.io 開放規範；加載後，在處理 ClickHouse 建表、寫查詢或設計數據管道時，Agent 應自動激活相關指導。人類可讀總覽見倉庫內 skills/clickhouse-best-practices/SKILL.md，完整編譯版見同目錄 AGENTS.md。

Cursor、Claude Code、Copilot 等平臺對 Skills 的掛載路徑與觸發方式以各產品文檔爲準；安裝命令以 ClickHouse 倉庫 README 爲準。

典型用法¶

場景一：評審一張新表的 DDL

把 CREATE TABLE 語句交給已加載該 Skill 的 Agent，要求其按 Schema Review 流程逐條讀 rules/schema-pk-*、rules/schema-types-*、rules/schema-partition-* 等文件，並按「Rules Checked / Findings / Recommendations」輸出。你會看到是否違反「ORDER BY 列低基數到高基數排序」「過濾列是否進入排序鍵前綴」「分區數量是否失控」等具體規則引用。

場景二：優化慢查詢

提供 SELECT 與表結構上下文，Agent 應優先查閱 query-join-*、query-index-skipping-indices、schema-pk-filter-on-orderby 等，檢查 JOIN 前是否過濾、算法是否匹配表規模、非排序鍵過濾是否考慮跳數索引。

場景三：Agent 直連 ClickHouse 探數

按 Skill 要求先走 rules/agent-connect-mcp.md 建立連接，再執行 rules/agent-discovery-schema.md 中的七步發現（庫 → 表 → 列與註釋 → 排序鍵 → 跳數索引 → 採樣 → EXPLAIN），最後在 rules/agent-query-safety.md 約束下帶 LIMIT 與超時執行查詢；超時或內存錯誤時縮小過濾範圍重試。

適用場景與注意¶

適合誰

• 用 Cursor、Claude Code、Copilot 等 Agent 做 ClickHouse schema 設計、SQL 評審或寫入策略討論的團隊；
• 希望 AI 建議與 clickhouse.com/docs/best-practices 一致、且能追溯「哪條規則」的讀者；
• 在 analytics 或 AI 數據管道里加大 ClickHouse 用量、又不想讓 Agent 憑泛化數據庫經驗亂改鍵或分區的人。

限制與注意

• Skill 是審查與流程指令，不替代你連上集羣做 EXPLAIN、看 system.parts 等實證；Agent 規則裏也寫明無適用規則時再查文檔或搜索。
• 倉庫 README 對「業務規則條數」的表述與 Skill 元數據（31 條、含 agent 類）略有層次差異；以 clickhouse-best-practices 目錄內 SKILL.md 及 rules/ 實際文件爲準。
• 全量 schema 設計若需「何時分區、如何選型架構」，可配合同倉庫的 clickhouse-architecture-advisor，best-practices 側重可檢查的 what，架構 Skill 側重 when/why/how。

結尾¶

clickhouse-best-practices 把 ClickHouse 官方最佳實踐拆成 31 條必查規則和固定審查流程，讓 Agent 在改表、改 SQL、談寫入之前先對齊列存與 MergeTree 的真實約束，並在輸出裏點名規則。安裝整包後，在處理 ClickHouse 相關任務時加載該 Skill 即可。

官方地址：https://github.com/clickhouse/agent-skills/tree/main/skills/clickhouse-best-practices