ClickHouse ベストプラクティス

ClickHouse のスキーマ設計、クエリ最適化、データインジェスション、AI エージェント接続をカバーする包括的ガイダンス。4 つの主要なカテゴリ(スキーマ、クエリ、インサート、エージェント)にわたる 31 のルールを含み、影響度でプライオリティ付けされています。

公式ドキュメント: ClickHouse Best Practices

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

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 vs 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 vs 通常の 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
• 高頻度小バッチ用に非同期インサートが有効になっている

---

出力形式

以下のように応答を構成してください:

## チェック済みルール
- `rule-name-1` - 準拠 / 違反発見
- `rule-name-2` - 準拠 / 違反発見
...

## 調査結果

### 違反
- **`rule-name`**: 問題の説明
  - 現在: [コードが何をしているか]
  - 要件: [何をすべきか]
  - 修正: [具体的な修正]

### 準拠
- `rule-name`: 正しい理由についての簡潔なメモ

## 推奨事項
[ルールを引用した優先度付けされた変更リスト]

---

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス	ルール数
1	PRIMARY KEY 選択	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

---

クイックリファレンス

スキーマ設計 - PRIMARY KEY (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 - ディクショナリ/非正規化 vs 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 - 最良のパフォーマンス用ネイティブ形式

インサート戦略 - ミューテーション (CRITICAL)

• insert-mutation-avoid-update - ALTER UPDATE ではなく ReplacingMergeTree
• insert-mutation-avoid-delete - 軽量 DELETE または DROP PARTITION

インサート戦略 - 最適化 (HIGH)

• insert-optimize-avoid-final - バックグラウンドマージに任せる

エージェント統合 - ディスカバリー (CRITICAL)

• agent-discovery-schema - クエリ前に常にスキーマを発見

エージェント統合 - セーフティ (CRITICAL)

• agent-query-safety - LIMIT、タイムアウト、段階的探索

エージェント統合 - 接続 + 形式 (HIGH)

• agent-connect-mcp - MCP + CLI セットアップ、認証情報発見、出力形式選択

---

適用時機

このスキルは以下に遭遇した場合に有効化します:

• ClickHouse に接続する AI エージェント(MCP、CLI、HTTP)

• ClickHouse 用エージェントワークフロー設計

• スキーマディスカバリーまたは探索リクエスト

• CREATE TABLE ステートメント

• ALTER TABLE 変更

• ORDER BY または PRIMARY KEY の議論

• データ型選択の質問

• 遅いクエリのトラブルシューティング

• JOIN 最適化リクエスト

• データインジェスションパイプライン設計

• 更新/削除戦略の質問

• ReplacingMergeTree または他の特殊エンジンの使用

• パーティショニング戦略決定

---

ルールファイル構造

rules/ 内の各ルールファイルには以下が含まれます:

• YAML frontmatter: タイトル、影響度、タグ
• 簡潔な説明: このルールが重要な理由
• 不正な例: アンチパターンと説明
• 正しい例: ベストプラクティスと説明
• 追加コンテキスト: トレードオフ、適用時機、リファレンス

---

フルコンパイル済みドキュメント

すべてのルールが展開されている完全なガイド: AGENTS.md

複数のルールをすばやくチェックする必要があり、個別ファイルを読みたくない場合は AGENTS.md を使用してください。