MongoDB スキーマ設計

MongoDB のデータモデリングパターンと反パターン（MongoDB により保守）。不正なスキーマは、MongoDB のパフォーマンスとコストの問題の根本原因となることがほとんどです。クエリとインデックスでは、根本的に間違ったモデルは修正できません。

適用するべき場合

以下の場合、このガイドラインを参照してください：

• ゼロから新しい MongoDB スキーマを設計する
• SQL/リレーショナルデータベースから MongoDB への移行
• パフォーマンス問題に対する既存のデータモデルのレビュー
• 低速クエリまたは増加するドキュメントサイズのトラブルシューティング
• 埋め込みと参照のどちらかを決める
• リレーションシップのモデリング（1対1、1対多、多対多）
• ツリー/階層構造の実装
• Atlas スキーマ提案またはパフォーマンスアドバイザーの警告を受けた
• 16MB ドキュメント制限に達した
• 既存のコレクションにスキーマ検証を追加する

クイックリファレンス

1. スキーマの反パターン - 3つのルール

• antipattern-unnecessary-collections - 均質なデータを複数のコレクションに分割することはしばしば反パターンです。このリファレンスを参照して、該当するかどうかを検証してください。
• antipattern-excessive-lookups - 互いに参照する過度に正規化されたコレクション、または頻繁でおそらく遅い $lookup 操作を見つけた場合、このリファレンスを参照して、問題があるかどうか、および修正方法を検証してください。
• antipattern-unnecessary-indexes - インデックスが重複しているか、クエリで使用されていない場合、このリファレンスを参照して、メリットのないオーバーヘッドを追加する不要なインデックスを特定して削除します。

2. スキーマの基礎 - 4つのルール

• fundamental-embed-vs-reference - 異なるタイプのリレーションシップ（1:1、1:few、1:many、many:many、ツリー/階層データ）をモデリングするアプローチと、アクセスパターンに基づいて埋め込みと参照のどちらかを決める方法について、このリファレンスを参照してください。
• fundamental-document-model - ドキュメントモデルの基礎。SQL または他の正規化されたデータから MongoDB のようなドキュメントデータベースへ移行する場合、このリファレンスを参照してください。
• fundamental-schema-validation - 新しいコレクションを作成する場合、または既存のコレクションに検証を追加する場合（例：一貫性のないドキュメント構造またはデータ品質の問題を発見した場合）、このリファレンスを参照してください。
• fundamental-document-size - ドキュメントが 16MB のハード制限に達したとき、または大きなドキュメントが原因でアクセスが予想より遅いとき、このリファレンスを参照してください。

3. デザインパターン - 11のルール

• pattern-approximation - 高頻度カウンターに概算値を使用する
• pattern-archive - 履歴データをパフォーマンスのため別のストレージ/コールドストレージに移動する
• pattern-attribute - 多くのオプションフィールドをキーバリューの属性に落とし込む
• pattern-bucket - 時系列または IoT データをバケットにグループ化する
• pattern-computed - 高価な集計を事前計算する
• pattern-document-versioning - ドキュメントの変更を追跡して、履歴クエリと監査証跡を実現する
• pattern-extended-reference - 関連エンティティからの頻繁にアクセスされるデータをキャッシュする
• pattern-outlier - ドキュメントのほぼ全てが、小さなサブセットより大きい場合に対応するコレクション、外れ値がメモリとインデックスコストを支配するのを防ぎます
• pattern-polymorphic - 異なるタイプのエンティティを同じコレクションに格納します。しばしば同じベースエンティティの異なるタイプがある場合（例：異なるタイプのユーザーまたは異なるタイプの製品）
• pattern-schema-versioning - スキーマの進化、ドリフトの防止、および安全なオンライン移行。一貫性のないドキュメント構造に遭遇したとき、またはアトミックに適用できないスキーマ変更を計画するときに参照してください。
• pattern-time-series-collections - 高頻度の時系列データにネイティブ時系列コレクションを使用する

重要な原則

「一緒にアクセスされるデータは、一緒に保存される必要があります。」

これが MongoDB の中核となる思想です。関連データを埋め込むことで、結合を排除し、ラウンドトリップを削減し、アトミック更新を可能にします。必要な場合のみ参照してください。

この思想を実装する中核的な方法は、MongoDB が柔軟なスキーマを公開しているという事実です。これは、異なるドキュメントに異なるフィールドを持たせることができ、異なる構造を持つこともできることを意味します。これにより、厳密なスキーマに制約されることなく、アクセスパターンに最も適合する方法でデータをモデリングできます。例えば、異なるドキュメントに異なるフィールドセットが含まれている場合、それがアプリケーションのニーズに役立つ限り、全く問題ありません。スキーマ検証を使用して、柔軟性を保ちながら特定のルールを実施することもできます。

重要な原則のもう1つの意味は、予想される読み取りと書き込みのワークロードに関する情報がスキーマ設計に非常に関連性があるようになるということです。異なるエンティティから複数の情報が頻繁にクエリまたは一緒に更新される場合、それは同じドキュメント内のそのデータの共存を優先することが大きなパフォーマンス上の利点をもたらす可能性があることを意味します。一方、特定の情報がめったにアクセスされない場合、必要以上に多くのデータを読み込むのを避けるために、それらを別々に保存することが理にかなっている場合があります。

スキーマ基礎のまとめ

• 埋め込みと参照: アクセスパターンに基づいて埋め込みと参照を選択します。データが常に一緒にアクセスされるとき（1:1、1:few、制限された配列、アトミック更新が必要）は埋め込み、データが独立してアクセスされるとき、リレーションシップが多対多のとき、または配列が無制限に成長する可能性があるときは参照します。
• 一緒にアクセスされるデータは一緒に保存: MongoDB の中核原則。エンティティではなくクエリを中心にスキーマを設計します。クロスコレクションの結合を排除し、ラウンドトリップを削減するために関連データを埋め込みます。API エンドポイント/ページを特定し、各エンドポイント/ページが返すデータをリストアップして、ドキュメントをそのクエリに合わせます。
• ドキュメントモデルを採用: SQL テーブルを 1:1 で MongoDB コレクションとして再作成しないでください。代わりに、結合されたテーブルを単一クエリの読み取りとアトミック更新のためのリッチなドキュメントに正規化を解除します。SQL から移行する場合、常に結合されるテーブルを特定し、単一のドキュメントにマージします。
• スキーマ検証: MongoDB の組み込みの $jsonSchema バリデータを使用して、無効なデータをデータベースレベルでキャッチします（タイプチェック、必須フィールド、列挙制約、配列サイズの制限）。既存のコレクションで validationLevel: "moderate" および validationAction: "warn" を開始し、その後 strict/error に厳格化します。
• 16MB ドキュメント制限: MongoDB ドキュメントは 16MB を超えることはできません。これはガイドラインではなく、ハード制限です。一般的な原因：無制限の配列、大きな埋め込みバイナリ、深くネストされたオブジェクト。無制限データを別のコレクションに移動し、$bsonSize でドキュメントサイズを監視することで、軽減します。

埋め込み/参照の決定フレームワーク

リレーションシップ	カーディナリティ	アクセスパターン	推奨事項
1対1	1:1	常に一緒	埋め込み
1対数個	1:N (N < 100)	通常は一緒	配列を埋め込み
1対多	1:N (N > 100)	しばしば別々	参照
多対多	M:N	異なる場合	双方向参照

これは粗いガイドラインであり、埋め込みか参照かは、具体的なアクセスパターン、データサイズ、読み取り/書き込みの頻度に依存します。常に実際のワークロードで検証してください。

使用方法

上記にリストされた各リファレンスファイルには、詳細な説明とコード例が含まれています。クイックリファレンスの説明を使用して、現在のタスクに関連するファイルを特定してください。

各リファレンスファイルには以下が含まれています：

• それが重要である理由の簡潔な説明
• 説明付きの不正なコード例
• 説明付きの正しいコード例
• 「使用しない場合」の例外
• パフォーマンスインパクトとメトリクス
• 検証診断

---

これらのルールはどのように機能するか

MongoDB MCP 統合

自動検証のため、MongoDB MCP Server を接続してください。

MCP サーバーが実行され接続されている場合、実際のスキーマ、ドキュメントサイズ、配列長、インデックス使用状況などを確認するために検証コマンドを自動的に実行できます。これにより、単なるコードパターンではなく、実際のデータに基づいたカスタマイズされた推奨事項を提供できます。

⚠️ セキュリティ: 安全のため --readOnly を使用してください。書き込み操作が必要な場合のみ削除してください。

接続されている場合、以下を自動的に実行できます：

• mcp__mongodb__collection-schema 経由でスキーマを推測
• mcp__mongodb__aggregate 経由でドキュメント/配列サイズを測定
• mcp__mongodb__db-stats 経由でコレクション統計をチェック

⚠️ アクションポリシー

明示的なご承認がない限り、書き込み操作は実行しません。

MCP 経由の書き込みまたは破壊的操作の前に、以下を実施します：(1) 正確な操作（コレクション、インデックス/バリデータ、影響を受けるドキュメントの推定数）を要約し、(2) 明示的な確認（yes/no）を求めます。曖昧または部分的な承認では進まりません。

操作タイプ	MCP ツール	アクション
読み取り（安全）	find、aggregate、collection-schema、db-stats、count	検証するために自動的に実行できます
書き込み（承認が必要）	update-many、insert-many、create-collection	コマンドを表示して承認をお待ちします
破壊的（承認が必要）	delete-many、drop-collection、drop-database	警告を出して明示的な確認が必要です

スキーマ変更またはデータ修正を推奨する場合：

1. 何をしたいのか、およびなぜかを説明します
2. 正確なコマンドを表示します
3. 実行前に承認をお待ちします
4. 「進めて」または「はい」と言った場合のみ、実行します

あなたのデータベース、あなたの決断です。 私は一方的に行動するためではなく、助言するためにここにいます。

一緒に進める

推奨事項に確信がない場合：

1. 提供した検証コマンドを実行してください
2. 出力を私と共有してください
3. 実際のデータに基づいて推奨事項を調整します

私たちはチームです。一緒にこれを正しくしましょう。