プレイブック

関連データが制限的で小さく、頻繁に一緒に読み取られるような、1対少数の関係が存在します。

→関連データをメインドキュメント内にネストされたオブジェクトまたは配列として埋め込みます。

理由: 単一のポイントリードで必要なすべてのデータを取得することで、読み取りパフォーマンスを最適化し、RUコストとレイテンシを最小限に抑えます。クライアント側のJOINを回避します。

リファレンス↗

"多"の側が無制限に増加するか、または"一"の側とは独立して更新されるような、1対多の関係です。

→関連アイテムを別々のドキュメントとして保存し、親ドキュメントのIDを参照として使用します。

理由: ドキュメントが2 MBのサイズ制限を超えるのを防ぎ、大きな埋め込み配列に対する更新での高いRUコストを回避します。

リファレンス↗

ドキュメントに時間とともに無制限に増加する可能性のある配列が含まれており、2 MBのドキュメントサイズ制限のリスクがあります（例：イベントログ、コメント）。

→配列を複数の「バケット」ドキュメントに分割します。バケットがサイズ/アイテムのしきい値に達したら、新しいバケットを作成します。

理由: 関連データの論理的なグループ化を維持しながら、個々のドキュメントサイズを管理しやすい状態に保ちます。

学生とコース、または記事とタグのような、多対多の関係をモデル化します。

→制限された関係の場合、両側で関係データを複製します（例：学生ドキュメントにコースIDを埋め込み、コースドキュメントに学生IDを埋め込む）。無制限の場合は、別の「結合」または「エッジ」ドキュメントコンテナを使用します。

理由: 非正規化は、結合を必要とせずに両方のクエリ方向（コース内の学生、学生のコース）を最適化します。結合コンテナは無制限のケース用です。

階層データ（例：組織図、製品カテゴリ）をモデル化し、ノードのすべての子孫をクエリする必要がある場合。

→各ドキュメントにすべての祖先IDまたは名前（パス）の配列を保存します。

理由: 単一の`ARRAY_CONTAINS`フィルターで効率的なサブツリークエリを可能にし、コストのかかる再帰的なルックアップを回避します。

ドキュメントに無制限の配列（例：ブログコメント）があるが、最も一般的なクエリでは最新のN個のアイテムのみが必要な場合。

→最新アイテムのサブセットをメインドキュメントに埋め込み、すべてのアイテムを個別の参照ドキュメントとして保存します。

理由: パフォーマンスとコストのために主要な読み取りパスを最適化しつつ、必要に応じて完全なデータセットへのアクセスも許可します。

エンティティの不変なイベントのシーケンスを保存し、現在の状態または分析的集計をクエリする必要がある場合。

→イベントをエンティティIDでパーティション分割された単一のコンテナに保存します。変更フィードまたはSynapse Linkを使用して、マテリアライズドビューまたは集計を計算および保存します。

理由: 完全な監査証跡を提供し、書き込みモデルをさまざまな読み取りモデルから分離することで、高い柔軟性を提供します。

特定の時点での関連データの状態を保持する必要がある場合（例：注文における顧客の住所）。

→参照するのではなく、関連データのコピー（スナップショット）をドキュメントに埋め込みます。

理由: 参照されるデータの将来の変更からドキュメントを分離することで、履歴の正確性を確保します。

高頻度の時系列データ（例：IoTセンサーの読み取り値）を取り込み、時間範囲でデバイスごとにクエリする場合。

→デバイスIDをパーティションキーとして使用します。各読み取り値ごとに1つのドキュメントではなく、読み取り値を時間で区切られたドキュメント（例：時間ごとまたは分ごと）に集計します。

理由: ドキュメント数と書き込みRUを劇的に削減し、パーティション内での効率的な時間範囲クエリのためにデータを併置します。

複数の作成、更新、または削除操作を単一のアトミックトランザクションとして実行する必要がある場合。

→SDKのTransactionalBatch機能を使用します。すべての操作は同じ論理パーティションキーを対象とする必要があります。

理由: 単一パーティション内で最大100の操作に対してACID保証を提供し、すべての操作が成功するか、またはすべてが一緒に失敗することを保証します。

ドキュメントが特定の期間（例：30日）後にコンテナから自動的に削除される必要がある場合。

→コンテナでTime to Live (TTL) を有効にし、デフォルトの`ttl`値を秒単位で設定します（例：30日なら2592000）。個々のドキュメントの`ttl`を-1にすると、デフォルトがオーバーライドされ、有効期限が切れるのを防ぎます。

理由: TTLは、残ったRUを使用してバックグラウンド削除を実行する費用のかからない機能であり、データライフサイクルを効率的かつ手間なく管理する方法を提供します。

Cosmos DBメタデータに関連付けられた大きなバイナリオブジェクト（画像、ビデオ、2MBを超えるドキュメント）を保存する必要がある場合。

→バイナリオブジェクトをAzure Blob Storageに保存します。Cosmos DBドキュメントには、メタデータとともにBLOBへのURIを保存します。

理由: Cosmos DBは構造化メタデータに最適化されており、2 MBのドキュメント制限があります。Blob Storageは、大きなオブジェクトストレージのための費用対効果が高くスケーラブルなサービスです。

同じデータが異なるプロパティによってクエリされる必要があり、非効率的なクロスパーティションクエリにつながる場合（例：顧客別、次に製品別で注文をクエリする）。

→変更フィードを使用して、同じデータを2番目のコンテナ（マテリアライズドビュー）に投入しますが、セカンダリクエリプロパティでパーティション分割します。

理由: 計算を読み取り時から書き込み時に移行し、複数のアクセスパターンに対して効率的な単一パーティションクエリを可能にします。

トランザクションワークロードに影響を与えることなく、ライブの運用データに対して複雑な分析クエリ（集計、結合）を実行する必要がある場合。

→Cosmos DBコンテナでAzure Synapse Linkを有効にします。Synapse serverless SQLまたはSparkプールを使用して、コンテナの分析ストアに対して分析クエリを実行します。

理由: ETL不要のクラウドネイティブなHTAPソリューションを提供します。列指向の分析ストアに対するクエリは、トランザクションRUを消費せず、非常に高性能です。

データ変更に応答して、スケーラブルで信頼性が高く、サーバーレスな方法でダウンストリームアクションをトリガーする必要がある場合。

→Cosmos DBトリガーを持つAzure Functionを使用します。このトリガーは変更フィードプロセッサライブラリを自動的に活用します。

理由: これはイベント駆動型アーキテクチャに推奨されるパターンです。自動スケーリング、チェックポイント、およびパーティションリース管理を提供します。

リファレンス↗

操作がデータベースをアトミックに更新し、メッセージングシステム（例：Service Bus、Event Hubs）にメッセージを公開する必要がある場合。

→データベースへの書き込みを実行します。変更フィードプロセッサを使用して、コミットされた変更を確実に読み取り、対応するメッセージをリトライロジックとともに公開します。

理由: 信頼性の低い二重書き込みや分散トランザクションの必要性を回避します。変更フィードは耐久性のあるアウトボックスとして機能し、メッセージの最終的な配信を保証します。

パフォーマンスとスケーラビリティを確保するために、新しいコンテナのパーティションキーを選択する場合。

→ほとんどすべてのポイントリードおよびクエリ操作に存在する、高いカーディナリティを持つプロパティを選択します。

理由: パーティションキーを最も一般的なクエリフィルターと整合させることで、ほとんどの操作が単一の論理パーティションにルーティングされることを保証し、これは最も効率的なアクセスパターンです。

リファレンス↗

単一のパーティションキー値が不釣り合いに大量のリクエストを受け取り、スロットリング（「ホットパーティション」）を引き起こす場合。

→元のキーにランダムなサフィックスまたは別の高いカーディナリティを持つプロパティを連結して、合成パーティションキーを作成します（例：`userId + "-" + random(1-10)`）。

理由: 単一の論理エンティティに対する書き込みおよび読み取り負荷を複数の物理パーティションに分散させ、スロットリングを軽減します。

大規模なパーティションを回避し、多レベルクエリをサポートするために、データが複数のレベル（例：テナント、次に年、次に月）でパーティション分割される必要がある場合。

→`["/tenantId", "/year"]`のようなパスの順序付き配列で階層型パーティションキーを構成します。

理由: サブパーティション分割により20 GBの論理パーティション制限を防ぎ、階層でフィルターするクエリに対してより効率的なルーティングを可能にします。

マルチリージョン書き込みが有効になっているグローバル分散アプリケーションが、同じドキュメントへの同時更新を処理する必要がある場合。

→単純な上書きには、Last-Writer-Wins (LWW) を使用します。マージロジックが必要な操作（例：カウンタのインクリメント、在庫の更新）には、マージストアドプロシージャを使用するカスタム競合解決ポリシーを使用します。

理由: カスタムマージロジックは、LWWで発生する可能性のあるデータ損失（例：失われたインクリメント）を防ぎ、重要なビジネス操作のデータ整合性を確保します。

グローバル分散アプリケーションの読み取りレイテンシ、可用性、およびデータ整合性のバランスを取る場合。

→バランスが良く、read-your-own-writesを実現するために、デフォルトでSession整合性を使用します。予測可能な読み取り遅延のためにBounded Stalenessを使用します。必要に応じて、特定の重要な書き込み/読み取り操作をStrong整合性に上書きします。

理由: Sessionは最も広く使用されているレベルであり、低レイテンシとクライアントセッション内での強力な保証を提供します。リクエストごとに上書きすることで柔軟性が得られます。

書き込み操作が過剰なRUを消費しており、クエリフィルターで使用されるドキュメントプロパティのごく一部のみである場合。

→デフォルトのインデックスポリシーからカスタムポリシーに切り替えます。クエリされるプロパティのパスを明示的に含め、他のすべてのパス（`excludedPaths`内の`"/*"`）を除外します。

理由: インデックス付きプロパティごとに書き込み時のRUコストが発生します。未使用のプロパティを除外することで、書き込みRU消費量とインデックスストレージサイズを大幅に削減できます。

リファレンス↗

頻繁なクエリが1つのプロパティでフィルタリングし、別のプロパティでソートする場合（例：`WHERE c.status = "active" ORDER BY c.timestamp DESC`）。

→クエリに表示される順序でプロパティの複合インデックスを作成します：`(status ASC, timestamp DESC)`。

理由: クエリエンジンがフィルタリングされソートされた結果をインデックスから直接提供できるようになり、コストのかかるインメモリソート操作を回避し、RU課金を大幅に削減します。

クエリが大きなドキュメントを取得するが、アプリケーションはそれらから1つか2つの小さなプロパティしか必要としない場合。

→`SELECT *`の代わりに、クエリプロジェクションを使用して必要なプロパティのみを選択します（例：`SELECT c.id, c.name FROM c`）。

理由: データベースエンジンからクライアントに転送されるデータペイロードサイズを削減することで、RUコストを削減します。

アプリケーションがドキュメントの更新を頻繁にポーリングするが、データはめったに変更されず、読み取りに高いRUコストがかかる場合。

→前回の読み取りからのETagを保存します。その後の読み取りでは、`If-None-Match`ヘッダーにETagを送信します。

理由: ドキュメントが変更されていない場合、Cosmos DBは最小限のRU課金（通常約1 RU）で304 Not Modifiedステータスを返し、コストと帯域幅を節約します。

ワークロードに変動性のある、または予測不可能なトラフィックパターンがあり、大幅なピークと谷がある場合。

→データベースまたはコンテナで自動スケーリングスループットを構成します。ピーク負荷に必要な最大RU/秒を設定します。

理由: 使用量に基づいて、最大RU/秒の10%から最大RU/秒の間でスループットを自動的にスケーリングし、アイドル状態のプロビジョニング済み容量に料金を支払わないことでコストを最適化します。

ワークロードが開発、テスト、または長期間のアイドル期間がある低トラフィックアプリケーション用である場合。

→Cosmos DBアカウントにサーバーレス容量モードを使用します。

理由: 操作ごとに消費されたRUのみを支払い、最小限のプロビジョニング容量はありません。これは散発的なワークロードにとって最も費用対効果の高いオプションです。

可能な限り迅速に大量のドキュメント（数千から数百万）を取り込むまたは変更する必要がある場合。

→SDKのバルクサポート機能を使用します（例：.NET SDK v3の`AllowBulkExecution = true`）。

理由: SDKは、操作のバッチ処理、同時実行の管理、および内部でのリトライ/スロットリングの処理により、高スループットを最適化し、シーケンシャルな操作をはるかに上回るパフォーマンスを発揮します。

大量のドキュメントを処理するストアドプロシージャがタイムアウトしている場合。

→バウンド実行を実装します。ストアドプロシージャは、5秒の実行制限に近づいているかどうかを確認し、もしそうであればクライアントに継続トークンを返します。その後、クライアントはトークンを使用してプロシージャを再呼び出しし、処理を再開します。

理由: ストアドプロシージャには厳格な実行時間制限があります。継続パターンは、長時間実行される多段階のサーバー側ロジックを処理するための標準的な方法です。

ビジネス上重要なアプリケーションが、地域的な障害が発生した場合に、最小限のデータ損失（RPO）と迅速な回復時間（RTO）を伴う高可用性を必要とする場合。

→Cosmos DBアカウントを複数の書き込みリージョンで構成し、自動フェイルオーバーを有効にします。

理由: 最低のRPOとRTOを提供します。データはリージョン間でレプリケートされ、障害が発生した場合は、Cosmos DBが自動的にセカンダリリージョンを新しいプライマリ書き込みリージョンに昇格させます。

偶発的なデータ削除や破損から、データベースを特定の時点に復元することで回復する能力が必要な場合。

→Cosmos DBアカウントでContinuous Backupモードを有効にします。

理由: Continuous Backupにより、保持期間内（7日または30日）の任意の時点（秒単位まで）に復元できます。復元操作は新しいアカウントを作成します。

リファレンス↗

コンプライアンス要件により、データ暗号化キーが顧客によって管理および制御されなければならない場合。

→Azure Key Vaultのキーを使用して、顧客管理キー（CMK）でCosmos DBアカウントを構成します。

理由: 保存時の暗号化のためのキーライフサイクル（ローテーションと失効を含む）を制御できる、追加のセキュリティ層を提供します。

最小権限の原則に従い、アプリケーションまたはユーザーにデータへのきめ細かなIDベースのアクセスを付与する必要がある場合。

→Azure AD統合を使用し、特定のコンテナまたはデータベースにスコープ設定された組み込みロール（例：Cosmos DB Built-in Data Reader）またはカスタムRBACロールを割り当てます。

理由: マスターキーの管理と共有の必要性を排除します。RBACは、監査可能でIDベースのアクセス制御を提供します。

Cosmos DBアカウントが、パブリックインターネットを介したトラフィックなしに、特定のAzure Virtual Network (VNet)内からのみアクセス可能である必要がある場合。

→VNetにCosmos DBアカウントのプライベートエンドポイントを作成し、ファイアウォール設定でパブリックネットワークアクセスを無効にします。

理由: プライベートエンドポイントは、VNet内のCosmos DBアカウントにプライベートIPアドレスを提供し、すべてのトラフィックが安全なAzureバックボーンを介して流れることを保証します。

HTTP 429（要求が多すぎます）スロットリングエラーの根本原因を診断する場合。

→Azure Monitorで「Normalized RU Consumption」メトリックを監視します。診断ログ（`CDBPartitionKeyRUConsumption`）を使用して、どのパーティションキーが最も多くのRUを消費しているかを特定します。

理由: 正規化されたRU消費量は、全体のスループットが枯渇しているかどうかを示します。パーティションレベルのログはホットパーティションを特定し、これは全体の使用量が低い場合でもスロットリングの一般的な原因です。

SLA遵守を確実にするために、要求レイテンシを監視し、アラートを設定する必要がある場合。

→Azure Monitorで「Server Side Latency P99」メトリックを監視します。このメトリックがSLAしきい値を超えた場合にアラートルールを作成します。

理由: P99レイテンシは、リクエストの99%にとって最悪のケースの体験を表し、Cosmos DBのSLAが基づいているものです。平均レイテンシよりもパフォーマンスの問題を示すより意味のある指標です。

コンプライアンス要件により、すべてのデータアクセス操作（読み取り、書き込み、クエリ）が監査されなければならない場合。

→Cosmos DBアカウントで診断設定を有効にし、`DataPlaneRequests`ログカテゴリをLog Analyticsワークスペースまたはストレージアカウントに転送します。

理由: `DataPlaneRequests`ログは、操作タイプ、クライアントIP、アクセスされたリソースなど、すべてのデータ操作に関する詳細情報を提供し、セキュリティ監査に不可欠です。

信頼できないクライアント（例：モバイルアプリ）が、特定のCosmos DBリソース（例：自身のパーティション内のドキュメントのみ）への一時的でスコープを絞ったアクセスを必要とする場合。

→ユーザーを認証する信頼できるミドルティアサービスを実装し、マスターキーを使用して短期間有効で権限がスコープ設定されたリソーストークンを生成し、クライアントに返します。

理由: これはクライアント側のアクセスにとって最も安全なパターンであり、マスターキーを公開することを避け、きめ細かな一時的なアクセス制御を提供します。