Cosmos DB Partition Key 設計集｜Synthetic Key・Hierarchical Partition Key・Hot Partition 対策

Partition Key は Cosmos DB の Container (テーブル相当) 内のドキュメントを論理パーティションに分散させる JSON プロパティ。Cosmos DB は物理的に複数のパーティション (Physical Partition、最大 20 GB / 10,000 RU/s) に分散保存し、Partition Key の値ハッシュで物理パーティションが決定される。Partition Key の選定は Cosmos DB のパフォーマンス・スケーラビリティ・コストすべてに影響する最重要設計判断で、後から変更不可 (Container 再作成が必要)。良い Partition Key は: 1) 高カーディナリティ (値のバリエーション 1,000+ 推奨)、2) アクセスパターン分散 (Hot Partition 回避)、3) クエリで頻繁にフィルタされる (Cross-partition Query 回避)、4) 書き込み分散 (Throttling 回避)。

4 つの条件すべてを満たすことが理想: 1) カーディナリティが高い (値のバリエーションが多い、最低 1,000 種類以上推奨)、2) アクセスパターンが分散される (Hot Partition を避ける、特定の少数値に集中しない)、3) クエリで頻繁にフィルタされる (Cross-partition Query を避ける、WHERE 句に含まれる)、4) 書き込みが分散される (Throttling を避ける、書き込み集中するキーは Hot Write Partition の原因)。例えばマルチテナント SaaS で tenantId を Partition Key にすると、特定大手テナント (10x のトラフィック) で Hot Partition 発生する場合、tenantId + bucketId のような合成キー (Synthetic Partition Key) が必要。設計初期で 4 条件を満たすキーが見つからない場合は、Hierarchical Partition Key (3 階層) や Synthetic Key の検討が必須です。

Synthetic Partition Key は、複数のプロパティを連結して人工的にカーディナリティを高める手法。例: tenantId_yyyymm (テナント ID + 年月) で月別パーティション、userId_random0-99 (ユーザー ID + ランダム 0-99) で 100 倍分散、deviceId_yyyymmdd (デバイス ID + 日付) で日別分散。書き込みパターン: 元プロパティから JavaScript で連結して新規プロパティとして保存し、それを Partition Key に指定。読み取りパターン: クエリでも合成キーを再構築してフィルタ。トレードオフ: 書き込みアプリケーションの修正が必要・特定キー範囲のクエリで Cross-partition になる可能性。マルチテナント SaaS で大手テナント・小規模テナントが混在する場合の Hot Partition 回避策として有効です。

Hierarchical Partition Key は 2023 GA の機能で、最大 3 階層の Partition Key を指定可能。例: TenantId / UserId / SessionId の 3 階層を指定すると、(1) TenantId だけでフィルタすると全 User・Session 横断クエリ (Cross-partition だが範囲限定)、(2) TenantId + UserId でフィルタすると User の全 Session、(3) TenantId + UserId + SessionId で完全 In-partition クエリ。従来は Synthetic Key で実現していた階層分散を、宣言的・効率的に実装可能。マルチテナント SaaS で『テナント単位の集計・ユーザー単位の操作・セッション単位の詳細』のような多階層クエリパターンに最適。新規プロジェクトでこの階層パターンに該当するなら Hierarchical Partition Key を採用するのが現代的なベストプラクティスです。

コスト・レイテンシ観点で避けるべきですが、すべて避けるのは現実的でないため『頻度の高いクエリで避ける』が原則。Cross-partition Query は全 Physical Partition に分散してクエリを実行 (Fan-out)、コスト数倍・レイテンシ大幅増。一方、In-partition Query (WHERE 句に Partition Key 含む) は単一 Physical Partition のみで完結、低コスト・低レイテンシ。実装パターン: 頻度高いユーザー向けクエリは In-partition に設計 (Partition Key を必須フィルタにする)、低頻度な管理者ダッシュボードは Cross-partition でも許容、Cross-partition 集計クエリは Synapse Link で別途実行 (Cosmos DB の負荷を回避)。x-ms-request-charge レスポンスヘッダで実 RU を計測し、想定外の Cross-partition クエリを早期発見することが運用上重要です。

Cosmos DB の物理パーティションは 1 個あたり最大 20 GB データ・10,000 RU/s スループットの制約があります。Partition Key の値で論理パーティションが決まり、複数論理パーティションが 1 物理パーティションにマップ。論理パーティションが Hot Spot 化して 10,000 RU/s に達すると Throttling (429 エラー) が発生。データが 20 GB に近づくと自動的に新規物理パーティションに分割 (Split)。Hot Partition 対策: 1) Partition Key 設計を見直して分散、2) Synthetic Key で人工分散、3) Read 中心なら追加 RU プロビジョニング (上限まで)、4) Write 集中ならアプリ側でバッチ処理・キュー化。本番運用では Cosmos DB Insights で Partition 利用率を継続監視し、80% 超えで設計見直しが必要です。

Cosmos DB の Throughput モード: 1) Manual Provisioned: 固定 RU/s 割り当て、最も予測可能なコスト、定常負荷向け。最低 400 RU/s から。2) Autoscale Provisioned: 最大 RU/s 指定 (例: 10,000)、10% (1,000) ~ 最大 (10,000) で自動スケール、変動負荷向け。月額は最大 RU の 1.5 倍上限。3) Serverless: 実消費のみ課金、開発・テスト・低トラフィック向け、Throughput 上限なし (5,000 RU/s 程度まで)、最大 1 TB データ。判断: 定常負荷 → Manual、変動 30%+ → Autoscale、低トラフィック・開発 → Serverless。本番運用では Reserved Capacity (1-3 年契約) で 20-65% 割引可能、コスト最適化に活用すべきです。

DP-420 (Cosmos DB Developer Specialty) で Partition Key 設計が深く問われる、本領域の本命認定。AZ-204 (Developer Associate、2026-07 リタイア注意) のドメイン 2 (Storage 15-20%) で Cosmos DB SDK 経由の操作、AZ-305 (Solutions Architect Expert) のドメイン 2 でデータストレージ選定 (Cosmos DB の API 選定・Consistency Level)、DP-700 (Fabric Data Engineer) で Synapse Link 経由のリアルタイム分析統合、AI-103 (2026-06 GA) で Cosmos DB を生成 AI / RAG 基盤として活用するパターン。Cosmos DB は Azure の主力 NoSQL データベースで、すべての関連エンジニアにとって Partition Key 設計の理解は必須スキルです。