cosmosdb-best-practices

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

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

個別のルールファイルが 73 件あり、rules/ ディレクトリにルールごとに 1 ファイルずつ配置されています。AzureCosmosDB/cosmosdb-agent-kit から同期されています。質問に回答する際は、関連するルールファイルのみを読み込んでください。すべてのファイルを一度に読み込まないでください。

適用するタイミング

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

• Cosmos DB のデータモデルを設計するとき
• パーティションキーを選択するとき
• クエリを記述または最適化するとき
• SDK のパターンを実装するとき
• パフォーマンスの問題についてコードをレビューするとき
• スループットとスケーリングを構成するとき
• グローバル分散アプリケーションを構築するとき
• ベクトル検索と RAG のパターンを実装するとき

ルール一覧

ルールはカテゴリのプレフィックスごとに分類されています。質問に応じて、関連するプレフィックスに一致するファイルを読み込んでください（たとえば、データモデリングには model-*.md、SDK の使用には sdk-*.md）。カテゴリの説明については、rules/_sections.md を参照してください。

1. データモデリング — CRITICAL（プレフィックス：model-）

• model-embed-related.md — 一緒に取得する関連データを埋め込む
• model-reference-large.md — 項目が大きくなった場合はデータを参照する
• model-avoid-2mb-limit.md — 項目のサイズを 2MB の上限より十分小さく保つ
• model-id-constraints.md — ID 値の長さと文字の制約に従う
• model-nesting-depth.md — 128 レベルのネスト深度の上限を超えない
• model-numeric-precision.md — IEEE 754 の数値精度の制限を理解する
• model-denormalize-reads.md — 読み取りの多いワークロードでは非正規化する
• model-schema-versioning.md — ドキュメントスキーマをバージョン管理する
• model-type-discriminator.md — ポリモーフィックデータには型識別子を使用する
• model-json-serialization.md — JSON のシリアル化を正しく処理する
• model-relationship-references.md — 一時的なハイドレーションと ID 参照を使用する

2. パーティションキーの設計 — CRITICAL（プレフィックス：partition-）

• partition-high-cardinality.md — カーディナリティの高いパーティションキーを選択する
• partition-avoid-hotspots.md — 書き込みを均等に分散する
• partition-hierarchical.md — 柔軟性を高めるために階層型パーティションキーを使用する
• partition-query-patterns.md — パーティションキーをクエリパターンに合わせる
• partition-synthetic-keys.md — 必要に応じて合成キーを作成する
• partition-key-length.md — パーティションキー値の長さの制限を守る
• partition-20gb-limit.md — 論理パーティションの 20GB の上限を考慮して計画する

3. クエリの最適化 — HIGH（プレフィックス：query-）

• query-avoid-cross-partition.md — クロスパーティションクエリを最小限に抑える
• query-use-projections.md — 必要なフィールドのみを射影する
• query-pagination.md — ページネーションには継続トークンを使用する
• query-avoid-scans.md — コンテナー全体のスキャンを避ける
• query-parameterize.md — パラメーター化クエリを使用する
• query-order-filters.md — 選択性の高い順にフィルターを並べる

4. SDK のベストプラクティス — 高（プレフィックス：sdk-）

• sdk-singleton-client.md — CosmosClient をシングルトンとして再利用する
• sdk-async-api.md — スループット向上のために非同期 API を使用する
• sdk-retry-429.md — retry-after を使用して 429 を処理する
• sdk-connection-mode.md — 本番環境では Direct モードを使用する
• sdk-preferred-regions.md — 優先リージョンを構成する
• sdk-excluded-regions.md — 問題が発生しているリージョンを除外する
• sdk-availability-strategy.md — 回復性を高めるための可用性戦略を構成する
• sdk-circuit-breaker.md — フォールトトレランスのためにサーキットブレーカーを使用する
• sdk-diagnostics.md — トラブルシューティングのために診断情報をログに記録する
• sdk-serialization-enums.md — 列挙型は整数ではなく文字列としてシリアル化する
• sdk-emulator-ssl.md — Cosmos DB Emulator の SSL と接続モードを構成する
• sdk-etag-concurrency.md — 楽観的同時実行制御に ETag を使用する
• sdk-java-content-response.md — 書き込み操作でコンテンツ応答を有効にする（Java）
• sdk-java-cosmos-config.md — 依存する Bean を使用して Spring Boot で Cosmos DB を構成する
• sdk-java-spring-boot-versions.md — Java のバージョンを Spring Boot の要件に合わせる
• sdk-local-dev-config.md — クラウドとの競合を避けるためにローカル開発環境を構成する
• sdk-newtonsoft-dependency.md — Newtonsoft.Json パッケージを明示的に参照する（.NET）
• sdk-spring-data-annotations.md — Spring Data Cosmos のエンティティにアノテーションを付ける
• sdk-spring-data-repository.md — CosmosRepository を正しく使用する

5. インデックス戦略 — 中〜高（プレフィックス：index-）

• index-exclude-unused.md — クエリで使用されないパスを除外する
• index-composite.md — ORDER BY に複合インデックスを使用する
• index-spatial.md — 地理空間クエリ用の空間インデックスを追加する
• index-range-vs-hash.md — 適切なインデックスの種類を選択する
• index-lazy-consistent.md — インデックス作成モードを理解する

6. スループットとスケーリング — 中（プレフィックス：throughput-）

• throughput-autoscale.md — 変動するワークロードにはオートスケールを使用する
• throughput-right-size.md — プロビジョニング済みスループットを適正な規模にする
• throughput-serverless.md — 開発／テストではサーバーレスを検討する
• throughput-burst.md — バースト容量を理解する
• throughput-container-vs-database.md — 割り当てレベルを慎重に選択する

7. グローバル分散 — 中（プレフィックス：global-）

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

8. 監視と診断 — 低〜中（プレフィックス：monitoring-）

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

9. 設計パターン — 高（プレフィックス：pattern-）

• pattern-change-feed-materialized-views.md — Change Feed を使用してマテリアライズドビューを作成する
• pattern-efficient-ranking.md — カウントベースまたはキャッシュを利用する方法でランキングを行う
• pattern-service-layer-relationships.md — サービスレイヤーを使用してドキュメント参照を解決する

10. ベクトル検索 — 高（プレフィックス：vector-）

• vector-enable-feature.md — アカウントでベクトル検索機能を有効にする
• vector-embedding-policy.md — コンテナーでベクトル埋め込みポリシーを定義する
• vector-index-type.md — ベクトルインデックス（QuantizedFlat または DiskANN）を構成する
• vector-distance-query.md — 類似性検索に VectorDistance() を使用する
• vector-normalize-embeddings.md — コサイン類似度のために埋め込みを正規化する
• vector-repository-pattern.md — ベクトル検索にリポジトリパターンを実装する

使用方法

各ルールは rules/ の下にある個別のファイルです。Cosmos DB に関する質問に回答する際は、 トピックに合致するプレフィックスに基づいて、関連するルールファイルのみを読み込みます。

• データモデリングに関する質問 → rules/model-*.md ファイルを読む
• パーティションキーに関する質問 → rules/partition-*.md ファイルを読む
• SDK／クライアントに関する質問 → rules/sdk-*.md ファイルを読む
• など

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加のコンテキストと参考資料

出典：AzureCosmosDB/cosmosdb-agent-kit