clickhouse-best-practices

ClickHouse のベストプラクティス

ClickHouse に関する包括的なガイダンスです。スキーマ設計、クエリの最適化、データ取り込み、AI エージェントとの接続を扱います。影響度に応じて優先順位付けされた、4 つの主要カテゴリ（スキーマ、クエリ、挿入、エージェント）にわたる 31 のルールが含まれています。

公式ドキュメント： ClickHouse のベストプラクティス

重要：このスキルの適用方法

ClickHouse に関する質問に回答する前に、次の優先順位に従ってください。

1. rules/ ディレクトリで該当するルールを確認する
2. ルールがある場合： そのルールを適用し、「rule-name によると…」という形式で回答内に引用する
3. ルールがない場合： LLM の ClickHouse に関する知識を使うか、ドキュメントを検索する
4. 確信が持てない場合： 最新のベストプラクティスをウェブ検索する
5. 必ず出典を引用する： ルール名、「ClickHouse に関する一般的なガイダンス」、または URL を示す

ルールを優先する理由： ClickHouse には、列指向ストレージ、スパースインデックス、MergeTree の仕組みなど、一般的なデータベースの直感では誤解を招く可能性のある特有の動作があります。これらのルールには、検証済みの 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 - JOIN 前のフィルタリング
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	エージェントによるスキーマ検出	CRITICAL	agent-discovery-	1
13	エージェントのクエリ安全性	CRITICAL	agent-query-	1
14	エージェントの接続とフォーマット	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 - 一致が 1 件のみ必要な場合は 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 - 複雑な JOIN にはリフレッシュ可能な MV を使用する

挿入戦略 - バッチ処理（CRITICAL）

• insert-batch-size - INSERT ごとに 10K～100K 行をバッチ処理する

挿入戦略 - 非同期処理（HIGH）

• insert-async-small-batches - 頻度の高い小規模バッチには非同期挿入を使用する
• insert-format-native - 最高のパフォーマンスを得るにはネイティブフォーマットを使用する

挿入戦略 - ミューテーション（重要）

• insert-mutation-avoid-update - ALTER UPDATE ではなく ReplacingMergeTree を使用します
• 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 を使用します。