cosmosdb-best-practices

Azure Cosmos DB のベストプラクティス

Azure Cosmos DB アプリケーション向けの包括的なパフォーマンス最適化ガイドです。12 のカテゴリにわたる 100 以上のルールを収録し、影響度に基づいて優先順位を付け、自動リファクタリングとコード生成を支援します。

適用する場面

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

• Cosmos DB のデータモデルを設計するとき
• パーティションキーを選択するとき
• クエリを作成または最適化するとき
• SDK のパターンを実装するとき
• ローカル開発で Cosmos DB Emulator を使用するとき
• 開発者向けツールで Cosmos DB のデータを検査または管理するとき
• Cosmos DB でベクトル検索または RAG 機能を実装するとき
• パフォーマンスの問題がないかコードをレビューするとき
• スループットとスケーリングを構成するとき
• グローバル分散アプリケーションを構築するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	データモデリング	CRITICAL	model-
2	パーティションキーの設計	CRITICAL	partition-
3	クエリの最適化	HIGH	query-
4	SDK のベストプラクティス	HIGH	sdk-
5	インデックス戦略	MEDIUM-HIGH	index-
6	スループットとスケーリング	MEDIUM	throughput-
7	グローバル分散	MEDIUM	global-
8	監視と診断	LOW-MEDIUM	monitoring-
9	設計パターン	HIGH	pattern-
10	開発者向けツール	MEDIUM	tooling-
11	ベクトル検索	HIGH	vector-

クイックリファレンス

1. データモデリング（CRITICAL）

• model-embed-related - 一緒に取得する関連データを埋め込む
• model-reference-large - 項目が大きくなりすぎる場合はデータを参照する
• model-avoid-2mb-limit - 項目のサイズを 2MB の上限より十分小さく保つ
• model-id-constraints - ID 値の長さと文字の制約に従う
• model-nesting-depth - 128 レベルのネスト深度制限を超えないようにする
• model-numeric-precision - IEEE 754 の数値精度の上限を理解する
• model-denormalize-reads - 事前計算済みの集計値を含め、読み取り中心のワークロード向けに非正規化する
• model-schema-versioning - ドキュメントスキーマをバージョン管理する
• model-type-discriminator - 多相データには型判別子を使用する
• model-json-serialization - Cosmos DB ドキュメントの JSON シリアル化を適切に処理する
• model-relationship-references - ドキュメント間の関係には ID 参照を使用し、一時的なハイドレーションを行う

2. パーティションキーの設計（CRITICAL）

• partition-high-cardinality - カーディナリティの高いパーティションキーを選択する
• partition-avoid-hotspots - 書き込みを均等に分散する
• partition-hierarchical - 柔軟性を高めるために階層型パーティションキーを使用し、レベルは広い範囲から狭い範囲の順に並べる
• partition-query-patterns - パーティションキーをクエリパターンに合わせる
• partition-synthetic-keys - 必要に応じて合成キーを作成する
• partition-key-length - パーティションキー値の長さの上限を守る
• partition-immutable-key - パーティションキーには変更されないプロパティを選ぶ
• partition-20gb-limit - 20GB の論理パーティション上限を考慮して計画する
• partition-rekey-migration - パーティションキーの不整合があるコンテナーを、Change partition key 機能で再キー化する

3. クエリの最適化（高）

• query-aggregate-single-pass - スコープを指定した集計クエリを1回実行して、最小値／最大値／平均値を計算します
• query-avoid-cross-partition - パーティションをまたぐクエリを最小限に抑えます
• query-use-projections - 必要なフィールドのみを射影します。射影には専用の結果型を使用してください
• query-pagination - ページネーションには継続トークンを使用します
• query-avoid-scans - コンテナー全体のスキャンを避けます
• query-parameterize - パラメーター化されたクエリを使用します
• query-order-filters - フィルターの順序はクエリエンジンに任せます。テキスト上の順序ではなく、インデックスが利用される述語を調整してください
• query-top-literal - TOP にはリテラルの整数を使用し、パラメーターは使用しません
• query-latest-by-timestamp - 明示的な ORDER BY と TOP 1 を使用して「最新」のドキュメントをクエリします
• query-olap-detection - 分析クエリを検出し、トランザクション用コンテナーではなく別の場所へリダイレクトします
• query-point-reads - ID とパーティションキーが分かっている場合は、クエリではなくポイント読み取り（ReadItem）を使用します

4. SDK のベストプラクティス（高）

• sdk-singleton-client - CosmosClient をシングルトンとして再利用する
• sdk-async-api - スループット向上のために非同期 API を使用する
• sdk-retry-429 - retry-after を使用して 429 を処理する
• sdk-connection-mode - 本番環境では Direct モードを使用する
• sdk-preferred-regions - 優先リージョンを構成する
• sdk-excluded-regions - 問題が発生しているリージョンを除外する
• sdk-availability-strategy - 可用性を高めるための戦略を構成する
• sdk-circuit-breaker - 耐障害性を高めるためにサーキットブレーカーを使用する
• sdk-diagnostics - トラブルシューティング用に診断情報をログに記録する
• sdk-serialization-enums - 列挙型を整数ではなく文字列としてシリアル化する
• sdk-emulator-ssl - Cosmos DB Emulator の SSL と接続モードを構成する
• sdk-ifnonematch-create - createItem で setIfNoneMatchETag("*") を使用し、重複をアトミックに拒否する（競合時は 409）
• sdk-no-shared-request-options - 遅延または同時実行される createItem 操作では、共有状態によるパーティションキーの上書きを避けるため、個別の CosmosItemRequestOptions インスタンスを使用する
• sdk-patch-incr - アトミックなカウンターのインクリメントには CosmosPatchOperations.increment() を使用する — 読み取り RU も、ETag の競合サイクルも不要
• sdk-bypage-empty-token - byPage() の呼び出し前に空文字列の継続トークンをチェックする — 最初のページには null を渡し、"" は渡さない
• sdk-etag-concurrency - 読み取り・変更・書き込み操作の楽観的同時実行制御に ETag を使用する
• sdk-java-content-response - 書き込み操作でコンテンツ応答を有効にする（Java）
• sdk-java-cosmos-config - Spring Boot で Cosmos DB の初期化を正しく構成する
• sdk-java-spring-boot-versions - Java のバージョンを Spring Boot の要件に合わせる
• sdk-local-dev-config - クラウドとの競合を避けるため、ローカル開発環境を構成する
• sdk-dotnet-cosmos-package-id - 廃止された Azure.Cosmos v4-preview パッケージではなく、Microsoft.Azure.Cosmos を使用する
• sdk-newtonsoft-dependency - Newtonsoft.Json パッケージを明示的に参照する
• sdk-python-async-deps - Python の非同期 SDK を使用する場合は aiohttp を含める
• sdk-spring-data-annotations - Spring Data Cosmos 用にエンティティにアノテーションを付ける
• sdk-spring-data-repository - CosmosRepository を正しく使用し、Iterable の戻り値の型を処理する
• sdk-langchain-cosmosdb-saver - 非同期コンテナークライアントを使用し、LangGraph のチェックポイントに CosmosDBSaver を使用する
• sdk-langchain-async-checkpointer - 非同期 Cosmos DB コンテナーはモジュールレベルではなく、起動時のルーチンで初期化する
• sdk-langchain-mcp-persistent-session - アプリケーションの実行中は MCP クライアントセッションを維持する
• sdk-langchain-mcp-tool-content-format - MCP ToolMessage のコンテンツで文字列形式とリスト形式の両方を処理する
• sdk-langgraph-mcp-tool-filtering - エージェントごとの割り当てに向けて、名前のプレフィックスで MCP ツールをフィルタリングする
• sdk-dotnet-namespace-collision - Microsoft.Azure.Cosmos 名前空間とドメインモデル（User、Database、Container など）の衝突を避ける
• sdk-ingestion-rate-control - 大量のデータ取り込みをレート制御する（同時実行数、retry-after、スループット制御）

5. インデックス作成戦略（中〜高）

• index-exclude-unused - クエリで使用されないパスを除外します
• index-path-syntax - 正しいパス表記（/?、/[]、/*）を使用します
• index-composite - ORDER BY には複合インデックスを使用します
• index-composite-direction - 複合インデックスの方向を ORDER BY に合わせます
• index-spatial - 地理空間クエリには空間インデックスを追加します
• index-range-vs-hash - 適切なインデックスの種類を選択します
• index-lazy-consistent - インデックス作成モードを理解します

6. スループットとスケーリング（中）

• throughput-autoscale - ワークロードが変動する場合はオートスケールを使用します
• throughput-right-size - プロビジョニング済みスループットを適切なサイズに設定します
• throughput-serverless - 開発／テストにはサーバーレスを検討します
• throughput-burst - バースト容量を理解します
• throughput-container-vs-database - 割り当てレベルを慎重に選択します
• throughput-idle-container-review - ライフサイクル上の対応に備えて、アイドル状態のコンテナーを確認します
• throughput-ttl-stale-data - ストレージ制限に達する前に、TTL で古いデータを期限切れにします
• throughput-serverless-migration - トラフィックの少ないプロビジョニング済みアカウントをサーバーレスに移行します

7. グローバル分散（中）

• global-multi-region - マルチリージョン書き込みを構成します
• global-consistency - 適切な整合性レベルを選択します
• global-conflict-resolution - 競合解決を実装します
• global-failover - 自動フェールオーバーを構成します
• global-read-regions - ユーザーの近くに読み取りリージョンを追加します
• global-zone-redundancy - HA のためにゾーン冗長性を有効にします
• global-multi-region-write-antipattern - アクティブ-アクティブが必要でない場合は、マルチリージョン書き込みを避けます

8. 監視と診断（低〜中）

• monitoring-ru-consumption - RU の消費量を追跡します
• monitoring-latency - P99 レイテンシを監視します
• monitoring-throttling - スロットリングをアラートで通知します
• monitoring-azure-monitor - Azure Monitor と統合します
• monitoring-diagnostic-logs - 診断ログを有効にします

9. 設計パターン（高）

• pattern-change-feed-materialized-views - Change Feed を使用して、パーティションをまたぐクエリを最適化します
• pattern-efficient-ranking - 効率的なランキングには、件数ベースまたはキャッシュを利用した方法を使用します
• pattern-service-layer-relationships - サービスレイヤーを使用して、ドキュメント参照を補完します
• pattern-langgraph-multi-agent - マルチエージェントのルーティングには、条件付きエッジを備えた StateGraph を使用します
• pattern-langgraph-interrupt-human - 人間が介在する確認フローには、LangGraph の interrupt を使用します
• pattern-langgraph-resume-checkpoint - 複数ターンの会話では、割り込み後にチェックポイントから LangGraph を再開します
• pattern-langgraph-agent-routing-cosmosdb - アクティブなエージェントを Cosmos DB に永続化し、ポイント読み取りによる決定的なルーティングを行います
• pattern-langgraph-fastapi-startup - 再試行ロジックを使用して、FastAPI の起動時に LangGraph エージェントを初期化します
• pattern-langgraph-chat-history-separate - チャット履歴はチェックポインターではなく、専用のコンテナーに保存します
• pattern-background-task-writes - FastAPI のバックグラウンドタスクを使用して、チャット履歴の書き込みをノンブロッキングで行います
• pattern-langgraph-async-cosmos-routing - LangGraph のルーティング関数では、Cosmos DB の同期呼び出しを asyncio.to_thread でラップします
• pattern-langgraph-async-cosmos-writes - 非同期ノード関数でのアクティブエージェントの書き込みには、asyncio.to_thread を使用します
• pattern-langgraph-agent-name-attribution - API 応答でエージェントを特定できるよう、AI メッセージにエージェント名をタグ付けします

10. 開発者向けツール（中）

• tooling-vscode-extension - 日常的な確認と管理には、VS Code 拡張機能を使用します
• tooling-emulator-setup - ローカルでの開発とテストには、Emulator を使用します

11. ベクトル検索（高）

• vector-enable-feature - ベクトル機能を使用する前に、アカウントでベクトル検索を有効にします
• vector-embedding-policy - ベクトルプロパティのベクトル埋め込みポリシーを定義します
• vector-index-type - インデックスポリシーでベクトルインデックスを構成します
• vector-normalize-embeddings - コサイン類似度の計算に備えて、埋め込みを正規化します
• vector-distance-query - 類似性検索には VectorDistance を使用します
• vector-repository-pattern - ベクトル検索にリポジトリパターンを実装します

12. 全文検索（高）

• fts-enable-capability - すべての FTS 関数の前提条件として、アカウントで EnableNoSQLFullTextSearch 機能を有効にします
• fts-full-text-policy - 正しい言語コード（en-US、大文字と小文字を区別）を指定して、コンテナーに fullTextPolicy を定義します
• fts-index-policy - 逆インデックスを構築するため、インデックスポリシーに fullTextIndexes エントリを追加します
• fts-contains-query - CONTAINS(LOWER(...)) の代わりに FullTextContains ／ FullTextContainsAll ／ FullTextContainsAny を使用します
• fts-score-ranking - BM25 による関連性ランキングには、ORDER BY RANK FullTextScore(path, term) を使用します
• fts-hybrid-query - FTS 述語と選択性の高いインデックス付きの等値／範囲フィルターを組み合わせます。述語のテキスト上の順序は、実行順序を制御しません

使用方法

詳しい説明とコード例については、上記のリンク先にあるルールファイルを使用してください。これらのリンクを使うと、フォルダー内を検索したりファイル名を推測したりすることなく、エージェントが関連するガイダンスに直接アクセスできます。

各ルールファイルには、以下が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 補足情報と参考資料