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

Azure Cosmos DB アプリケーションのための包括的なパフォーマンス最適化ガイドです。12カテゴリにわたる100以上のルールを含み、 自動リファクタリングとコード生成をガイドするため、インパクト順に優先順位付けされています。

適用すべき場面

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

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

ルールカテゴリ（優先順位順）

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

クイックリファレンス

1. データモデリング（重大）

• 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. パーティションキー設計（重大）

• partition-high-cardinality - 高カーディナリティのパーティションキーを選択する
• partition-avoid-hotspots - 書き込みを均等に分散させる
• partition-hierarchical - 柔軟性のための階層的パーティションキーを使用；レベルを広い→狭い順に並べる
• partition-query-patterns - パーティションキーをクエリパターンと一致させる
• partition-synthetic-keys - 必要に応じて合成キーを作成する
• partition-key-length - パーティションキー値の長さ制限に従う
• partition-immutable-key - パーティションキーとして不変プロパティを選択する
• partition-20gb-limit - 20GB の論理パーティション制限を計画する

3. クエリ最適化（高）

• query-aggregate-single-pass - min/max/avg をスコープ付き集計クエリで一度に計算する
• 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 - 429 を retry-after で処理する
• sdk-connection-mode - 本番環境では Direct モードを使用する
• sdk-preferred-regions - 優先リージョンを構成する
• sdk-excluded-regions - 問題が発生しているリージョンを除外する
• sdk-availability-strategy - 回復力のために可用性戦略を構成する
• sdk-circuit-breaker - フォルトトレランスのためにサーキットブレーカーを使用する
• sdk-diagnostics - トラブルシューティング用に診断をログに出力する
• sdk-serialization-enums - enum を整数ではなく文字列としてシリアライズする
• sdk-emulator-ssl - Cosmos DB Emulator 用に SSL と接続モードを構成する
• sdk-ifnonematch-create - createItem で setIfNoneMatchETag("*") を使用して重複を原子的に拒否する（競合時は409）
• sdk-no-shared-request-options - 複数の createItem 呼び出しで CosmosItemRequestOptions インスタンスを再利用しない — SDK は内部でそれを変更し、2番目の呼び出しで誤ったパーティションキーを引き起こす
• sdk-patch-incr - 原子的なカウンター増分に CosmosPatchOperations.incr() を使用する — 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 等）の衝突を避ける

5. インデックス戦略（中～高）

• index-exclude-unused - クエリされないパスを除外する
• 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 - 割り当てレベルを賢く選択する

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

• global-multi-region - マルチリージョン書き込みを構成する
• global-consistency - 適切な一貫性レベルを選択する
• global-conflict-resolution - 競合解決を実装する
• global-failover - 自動フェイルオーバーを構成する
• global-read-regions - ユーザーの近くに読み取りリージョンを追加する
• global-zone-redundancy - HA のためにゾーン冗長性を有効にする

8. 監視 & 診断（低～中）

• monitoring-ru-consumption - RU 消費を追跡する
• monitoring-latency - P99 レイテンシを監視する
• monitoring-throttling - スロットリングについて警告する
• monitoring-azure-monitor - Azure Monitor を統合する
• monitoring-diagnostic-logs - 診断ログを有効にする

9. デザインパターン（高）

• pattern-change-feed-materialized-views - クロスパーティションクエリ最適化のため変更フィードを使用する
• pattern-efficient-ranking - 効率的なランキングのためカウントベースまたはキャッシュ方式を使用する
• pattern-service-layer-relationships - サービスレイヤーを使用してドキュメント参照をハイドレートする
• pattern-langgraph-multi-agent - マルチエージェントルーティング用に条件付きエッジを持つ StateGraph を使用する
• pattern-langgraph-interrupt-human - 人間参加確認フロー用に LangGraph interrupt を使用する
• pattern-langgraph-resume-checkpoint - マルチターン会話のため interrupt 後のチェックポイントから 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 ルーティング関数用に asyncio.to_thread で Cosmos DB 同期呼び出しをラップする
• 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 - アカウントで EnableNoSQLFullTextSearch 機能を有効にする — すべての FTS 関数の前提条件
• fts-full-text-policy - コンテナで fullTextPolicy を定義する；正しい言語コード（en-US、大文字小文字区別）で
• 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 述語と範囲/等価フィルタを組み合わせる；最も選別的なフィルタを最初に置く

使い方

詳細な説明とコード例については、上記のリンク済みルールファイルを使用してください。リンクはエージェントに関連するガイドへの直接パスを 提供し、フォルダスキャンや推論されたファイル名に依存しません。

各ルールファイルには以下が含まれます：

• それが重要である理由の簡潔な説明
• 説明付き不正なコード例
• 説明付き正しいコード例
• 追加のコンテキストと参考資料

全コンパイルドキュメント

すべてのルールを展開した完全なガイドについては：AGENTS.md