mongodb-schema-design

MongoDB スキーマ設計

MongoDB が管理する、MongoDB のデータモデリングパターンとアンチパターンです。不適切なスキーマは、MongoDB のパフォーマンスやコストに関する問題の大半の根本原因です。クエリやインデックスでは、根本的に誤ったモデルを修正できません。

適用する場面

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

• MongoDB の新しいスキーマを一から設計するとき
• SQL／リレーショナルデータベースから MongoDB に移行するとき
• パフォーマンス上の問題について、既存のデータモデルを確認するとき
• クエリの遅延やドキュメントサイズの増大を調査するとき
• 埋め込みと参照のどちらを選ぶか判断するとき
• リレーションシップ（1 対 1、1 対多、多対多）をモデル化するとき
• ツリー／階層構造を実装するとき
• Atlas Schema Suggestions や Performance Advisor の警告が表示されたとき
• ドキュメントの 16MB 制限に達したとき
• 既存のコレクションにスキーマ検証を追加するとき

クイックリファレンス

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

• antipattern-unnecessary-collections - 同種のデータを複数のコレクションに分割することは、多くの場合アンチパターンです。該当するかどうかを確認するには、このリファレンスを参照してください。
• antipattern-excessive-lookups - 過度に正規化され、相互に参照し合うコレクションや、頻繁に実行されて遅くなる可能性のある $lookup 操作に遭遇した場合、問題があるかどうかとその解決方法を確認するには、このリファレンスを参照してください。
• antipattern-unnecessary-indexes - インデックスが重複している場合やクエリで使用されていない場合に、このリファレンスを参照して、メリットがないのにオーバーヘッドを増やす不要なインデックスを特定し、削除してください。

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

• fundamental-embed-vs-reference - さまざまな種類のリレーションシップ（1 対 1、1 対少数、1 対多、多対多、ツリー／階層データ）のモデル化方法や、アクセスパターンに基づいて埋め込みと参照のどちらを選ぶか判断する方法については、このリファレンスを参照してください。
• 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 - 高頻度の時系列データにはネイティブの時系列コレクションを使用します

アクセスパターンの分析

より広いコンテキストを理解せずに、すぐにパターンやスキーマ変更を推奨しないでください。ユーザーと一緒にアクセスパターンを分析し、課題と最適化の機会を特定します。

ワークフロー

ステップ 1：環境を評価する ユーザーに次のことを尋ねます。

• これは新しい設計ですか。それとも、分析対象となる既存のアクセスパターンを持つ本番データベースがありますか？
• 本番データがある場合、それは Atlas 上にありますか？ある場合、どのティアですか？（M0/M2/M5 と M10 以上）

ステップ 2：ワークロードの種類を判断する ワークロードは読み取り中心、書き込み中心、それともバランス型ですか？これによって、どの診断情報源が最も関連性が高いかが変わります。 ユーザーに尋ねます。

• これらのコレクションの主なワークロードは何ですか？読み取り中心（分析、レポート、検索）、書き込み中心（ログ記録、IoT データの取り込み、頻繁な更新）、それともバランス型ですか？

db.serverStatus().opcounters で確認します。

ステップ 3：最適な情報源をユーザーと選ぶ トレードオフを説明しながら、状況に最適な情報源を推奨します。スキーマ設計の判断では、全体像を把握するために複数の情報源を組み合わせる必要があることがよくあります。

ステップ 4：分析を進める 情報源を選択してから、データを取得するか、分析の手順をユーザーに案内します。

ソース

• クエリ統計 - 記録されたクエリの実行時統計を返し、クエリの形状と頻度を確認できます。制限事項：現在は読み取り操作のみを取得します（書き込みパターンを把握するには、ほかのソースと組み合わせてください）。Atlas M10 以上のティアが必要です。
• Atlas のスロークエリログ - パフォーマンスのボトルネックを特定するため、スロークエリ（形状ではなく実際のクエリ）を確認できます。読み取りと書き込みの両方を取得します。Atlas M10 以上のティアが必要です。
• コードベース - アプリケーションコード内の実際のクエリを調べ、アクセスパターンを把握します。特に、新しいアプリケーションやワークロードが変化している場合に有用です。より全体的な状況を把握するため、クエリ統計と併用できます。
• 自然言語による入力 - 通常のクエリやアクセスパターンを自然言語で説明するようユーザーに依頼します。唯一のソースとして使うことも、ほかのソースを補完して検証するために使うこともできます。データやコードベースには反映されていない背景知識をユーザーが持っている場合があります。

クエリ統計とスロークエリログの組み合わせ：

包括的に分析するには、両方を併用します。

1. クエリ統計 → 頻繁なアクセスパターンを特定します（実行頻度の高いクエリ）。
2. スロークエリログ → パフォーマンスのボトルネックを特定します（処理に時間がかかるクエリ）。
3. 頻繁で、かつ処理が遅いクエリにスキーマ最適化の焦点を当てます（最も大きな効果が得られます）。

重要な原則

「一緒にアクセスされるデータは、一緒に格納すべきです。」

これが MongoDB の中核となる理念です。関連データを埋め込むことで、結合が不要になり、往復回数が減り、アトミックな更新が可能になります。参照は必要な場合にのみ使用してください。

この理念を実現するための重要な方法の一つが、MongoDB が柔軟なスキーマを提供していることです。これは、ドキュメントごとに異なるフィールドや構造を持てるという意味です。そのため、固定的なスキーマに縛られず、アクセスパターンに最適な方法でデータをモデル化できます。たとえば、ドキュメントごとにフィールドのセットが異なっていても、アプリケーションのニーズを満たしていれば問題ありません。また、スキーマ検証を使って、柔軟性を保ちながら特定のルールを適用することもできます。

この重要な原則から、想定される読み取りと書き込みのワークロードに関する情報も、スキーマ設計において非常に重要になります。異なるエンティティの情報が一緒にクエリまたは更新されることが多い場合、それらのデータを同じドキュメント内にまとめて格納することで、大幅なパフォーマンス向上につながります。一方、一緒にアクセスされることがまれな情報は、必要以上のデータを読み込まないよう、別々に格納するほうが適切な場合があります。

スキーマの基本原則のまとめ

• 埋め込みと参照：アクセスパターンに基づいて、埋め込みと参照のどちらを選ぶか決めます。データに常に一緒にアクセスする場合（1:1、1:少数、上限のある配列、アトミックな更新が必要な場合）は埋め込み、データに個別にアクセスする場合、リレーションシップが多対多の場合、または配列が際限なく増える可能性がある場合は参照を選びます。
• 一緒にアクセスするデータは一緒に保存する：これは 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）明示的な確認（はい／いいえ）を求めます。不完全または曖昧な承認では、処理を進めません。

操作の種類	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. 実際のデータに基づいて、提案を調整します

私たちはチームです。一緒に正しく進めましょう。