clickhouse-best-practices

ClickHouse 最佳實務

涵蓋 ClickHouse 結構設計、查詢最佳化、資料匯入及 AI 代理連線的完整指引。包含 4 大類別（結構、查詢、插入、代理）共 31 條規則，依影響程度排序。

官方文件： ClickHouse 最佳實務

重要：如何套用此技能

在回答 ClickHouse 問題前，請依下列優先順序進行：

1. 檢查適用的規則 在 rules/ 目錄中
2. 若有規則存在： 套用規則並在回應中引用，格式為「根據 rule-name...」
3. 若無規則存在： 使用 LLM 的 ClickHouse 知識或搜尋文件
4. 若不確定： 使用網路搜尋最新最佳實務
5. 務必標註來源： 規則名稱、「一般 ClickHouse 指引」或 URL

為什麼規則優先： ClickHouse 有特定的行為（欄位式儲存、稀疏索引、合併樹機制），一般資料庫直覺可能誤導。這些規則編碼了經過驗證、ClickHouse 專屬的指引。

---

代理連線與查詢工作流程

在查詢 ClickHouse 之前，代理必須建立連線並遵循探索工作流程：

1. rules/agent-connect-mcp.md - 連線設定（MCP + CLI）、憑證探索、輸出格式選擇
2. rules/agent-discovery-schema.md - 關鍵：7 步驟結構探索工作流程
3. rules/agent-query-safety.md - 關鍵：LIMIT、逾時、漸進式探索

每個代理工作階段應遵循此順序：

1. 連線 — 透過 MCP 或 CLI 建立連線（參見 agent-connect-mcp）
2. 探索 — 資料庫 → 資料表 → 欄位 + 註解 → 排序鍵 → 跳躍索引 → 取樣 → EXPLAIN
3. 規劃 — 利用排序鍵和跳躍索引知識撰寫有效率的 WHERE 子句
4. 執行 — 使用 LIMIT 和逾時執行查詢
5. 復原 — 遇到逾時或記憶體錯誤時，縮小過濾條件並重試（參見 agent-query-safety）

子代理架構備註

若您的系統將 ClickHouse 任務分派給專門的子代理：

• 結構探索 + 查詢執行：任何模型皆可 — 步驟是程序性的
• 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 演算法
• [ ] 對非 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
• [ ] 高頻小批次啟用非同步插入

---

輸出格式

請依下列結構組織回應：

## 已檢查規則
- `rule-name-1` - 符合 / 發現違規
- `rule-name-2` - 符合 / 發現違規
...

## 發現

### 違規
- **`rule-name`**：問題說明
  - 現狀：[程式碼目前的作法]
  - 要求：[應有的作法]
  - 修正：[具體修正方式]

### 符合
- `rule-name`：簡短說明為何正確

## 建議
[依優先順序列出變更，引用規則]

---

規則類別（依優先順序）

優先順序	類別	影響	前綴	規則數量
1	主鍵選擇	關鍵	schema-pk-	4
2	資料型別選擇	關鍵	schema-types-	5
3	JOIN 最佳化	關鍵	query-join-	5
4	插入批次	關鍵	insert-batch-	1
5	避免突變	關鍵	insert-mutation-	2
6	分割策略	高	schema-partition-	4
7	跳躍索引	高	query-index-	1
8	具體化視圖	高	query-mv-	2
9	非同步插入	高	insert-async-	2
10	避免 OPTIMIZE	高	insert-optimize-	1
11	JSON 使用	中	schema-json-	1
12	代理結構探索	關鍵	agent-discovery-	1
13	代理查詢安全	關鍵	agent-query-	1
14	代理連線與格式	高	agent-connect-	1

---

快速參考

結構設計 - 主鍵（關鍵）

• schema-pk-plan-before-creation - 建立資料表前規劃 ORDER BY（不可變）
• schema-pk-cardinality-order - 欄位依低到高基數排序
• schema-pk-prioritize-filters - 納入經常過濾的欄位
• schema-pk-filter-on-orderby - 查詢過濾條件必須使用 ORDER BY 前綴

結構設計 - 資料型別（關鍵）

• schema-types-native-types - 使用原生型別，不要全部用 String
• schema-types-minimize-bitwidth - 使用能容納資料的最小數值型別
• schema-types-lowcardinality - 對少於 10K 唯一值的字串使用 LowCardinality
• schema-types-enum - 對有限值集合使用 Enum 並驗證
• schema-types-avoid-nullable - 避免 Nullable；改用 DEFAULT

結構設計 - 分割（高）

• schema-partition-low-cardinality - 分割區數量維持在 100-1,000
• schema-partition-lifecycle - 分割用於資料生命週期，而非查詢
• schema-partition-query-tradeoffs - 了解分割修剪的取捨
• schema-partition-start-without - 考慮先不分割

結構設計 - JSON（中）

• schema-json-when-to-use - JSON 用於動態結構；已知欄位用型別欄位

查詢最佳化 - JOIN（關鍵）

• query-join-choose-algorithm - 根據資料表大小選擇演算法
• query-join-use-any - 只需一個匹配時使用 ANY JOIN
• query-join-filter-before - 聯結前先過濾資料表
• query-join-consider-alternatives - 考慮字典/反正規化替代 JOIN
• query-join-null-handling - join_use_nulls=0 以使用預設值

查詢最佳化 - 索引（高）

• query-index-skipping-indices - 對非 ORDER BY 的過濾欄位使用跳躍索引

查詢最佳化 - 具體化視圖（高）

• query-mv-incremental - 增量具體化視圖用於即時聚合
• query-mv-refreshable - 可重新整理的具體化視圖用於複雜聯結

插入策略 - 批次（關鍵）

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

插入策略 - 非同步（高）

• insert-async-small-batches - 高頻小批次使用非同步插入
• insert-format-native - 使用 Native 格式以獲得最佳效能

插入策略 - 突變（關鍵）

• insert-mutation-avoid-update - 使用 ReplacingMergeTree 而非 ALTER UPDATE
• insert-mutation-avoid-delete - 使用輕量 DELETE 或 DROP PARTITION

插入策略 - 最佳化（高）

• insert-optimize-avoid-final - 讓背景合併自行運作

代理整合 - 探索（關鍵）

• agent-discovery-schema - 查詢前務必探索結構

代理整合 - 安全（關鍵）

• agent-query-safety - LIMIT、逾時、漸進式探索

代理整合 - 連線與格式（高）

• agent-connect-mcp - MCP + CLI 設定、憑證探索、輸出格式選擇

---

何時套用

當您遇到以下情況時，此技能會啟動：

• AI 代理連線到 ClickHouse（MCP、CLI、HTTP）

• 代理工作流程設計用於 ClickHouse

• 結構探索或查詢請求

• CREATE TABLE 陳述式

• ALTER TABLE 修改

• ORDER BY 或 PRIMARY KEY 討論

• 資料型別選擇問題

• 慢查詢疑難排解

• JOIN 最佳化請求

• 資料匯入管線設計

• 更新/刪除策略問題

• ReplacingMergeTree 或其他特殊引擎使用

• 分割策略決策

---

規則檔案結構

rules/ 中的每個規則檔案包含：

• YAML 前置資料：標題、影響等級、標籤
• 簡短說明：為什麼這條規則重要
• 錯誤範例：反模式與說明
• 正確範例：最佳實務與說明
• 額外背景：取捨、何時套用、參考資料

---

完整彙編文件

如需包含所有規則的完整指南：AGENTS.md

當您需要快速檢查多條規則而不逐一閱讀檔案時，請使用 AGENTS.md。