Azure Cosmos DBの「Partitioning and horizontal scaling」でまず押さえるべき結論は、既存システムが突然動かなくなるような破壊的変更ではなく、パーティションキー設計の失敗を避けるための判断基準がより明確になったという点です。特に、ホットパーティション、クロスパーティションクエリ、論理パーティションの20GB上限、移行時のコンテナー再作成、階層型パーティションキーやグローバルセカンダリインデックスの使いどころを確認する必要があります。Microsoft Learnの英語版では最終更新が2026年5月21日と表示されているため、日本時間や社内の更新管理では2026年5月22日付の情報として扱う場合も、公式ページの表示日を併せて確認しておくと安全です。(Microsoft Learn)
2026年5月更新で押さえるべきポイント
今回確認すべき中心テーマは、Azure Cosmos DBのパーティション分割そのものの基本仕様に加えて、どのパーティションキーを選ぶべきか、どの選び方が危険か、既存コンテナーをどう見直すべきかです。
公式記事では、Azure Cosmos DBがコンテナー内の項目をパーティションキーの値に基づいて論理パーティションへ分割し、データとスループットを物理パーティションへ分散して水平スケーリングする仕組みを説明しています。対象はNoSQL、MongoDB、Apache Cassandra、Apache Gremlin、Tableの各APIです。(Microsoft Learn)
特に実務で重要なのは、次の4点です。
| 確認ポイント | 実務上の意味 | 主な対象者 |
|---|---|---|
| パーティションキーは後からその場で変更できない | 設計ミスは新コンテナーへの移行やデータコピーが必要になる | アーキテクト、開発者 |
| 論理パーティションは最大20GBが目安になる | 特定のキー値にデータが集中するとスケールの限界に近づく | 管理者、SRE |
| RU消費が偏るとホットパーティションになる | 429エラー、レイテンシ増加、コスト増につながる | 開発者、運用担当 |
/id、status、ランダムGUIDなどの使い方に注意が必要 | 一見便利でも、クエリや負荷分散と合わないと性能問題を起こす | 開発者 |
MicrosoftDocsの更新履歴では、2026年5月13日に「パーティションキーのアンチパターン」に関するガイダンス追加や文言調整が行われています。つまり、今回の更新は新機能だけを見るのではなく、既存設計を見直すための警告サインが整理された更新として読むのが実務的です。(GitHub)
Azure Cosmos DBのパーティション分割とは
Azure Cosmos DBでは、コンテナー内のデータを「論理パーティション」に分けます。論理パーティションは、同じパーティションキー値を持つ項目の集合です。
たとえば、UserIDをパーティションキーにした場合、UserIDが1,000種類あれば、1,000個の論理パーティションが作られます。各項目は、パーティションキーと項目IDの組み合わせによって一意に識別されます。(Microsoft Learn)
ここで混同しやすいのが「シャードキー」という言葉です。分散データベースではシャードキーと呼ばれることがありますが、Azure Cosmos DBの公式ドキュメントやAPIではパーティションキーが正式な用語です。設計書、コードコメント、運用手順書では「シャードキー」ではなく「パーティションキー」に統一すると、Azureの公式情報と照合しやすくなります。(Microsoft Learn)
論理パーティションと物理パーティションの違い
Azure Cosmos DBのスケーリングを理解するには、論理パーティションと物理パーティションを分けて考える必要があります。
| 種類 | 役割 | 管理者・開発者が意識すべきこと |
|---|---|---|
| 論理パーティション | 同じパーティションキー値を持つデータのまとまり | キー値ごとのデータ量、RU消費、トランザクション範囲 |
| 物理パーティション | Azure Cosmos DB内部でデータとスループットを分散する単位 | 直接制御できない。設計ではパーティションキーの分散を重視する |
公式情報では、論理パーティションの数に制限はない一方で、各論理パーティションは最大20GBのデータを格納できるとされています。また、ストアドプロシージャやトリガー内のトランザクションは、1つの論理パーティション内に限定されます。(Microsoft Learn)
物理パーティションはAzure Cosmos DBが管理する内部実装です。個々の物理パーティションは最大10,000 RU/sのスループットと最大50GBのデータを扱うと説明されています。物理パーティションは直接操作できないため、管理者や開発者は「物理パーティションをどう配置するか」ではなく、論理パーティション間でRU消費とデータ量が偏らないパーティションキーを選ぶことに集中すべきです。(Microsoft Learn)
重要なのは、スループットが物理パーティションに均等配分される点です。たとえば、あるコンテナーで一部のパーティションキー値だけにアクセスが集中すると、全体として十分なRU/sを確保していても、その一部のパーティションでレート制限が発生することがあります。これがホットパーティションです。
影響を受けやすいシステム
今回の公式情報を特に確認すべきなのは、次のようなAzure Cosmos DB環境です。
| システムの特徴 | 起こりやすい問題 | 確認すべき項目 |
|---|---|---|
| マルチテナントSaaS | 大口テナントだけデータ量やアクセスが突出する | tenantId単独で20GBや10,000RU/sに近づいていないか |
| EC・注文管理 | 特定顧客、特定日、特定店舗に書き込みが集中する | customerId、orderDate、storeIdの偏り |
| IoT・ログ収集 | 特定デバイスや時間帯に書き込みが集中する | 時間バケットや合成キーの必要性 |
| 読み取り中心のAPI | パーティションキーを含まない検索が多い | クロスパーティションクエリのRU消費 |
| 既存設計を長く使っている環境 | 初期設計時よりデータ量やクエリが変わっている | パーティションキー変更やGSI検討の必要性 |
小規模な検証環境では問題が見えなくても、本番でデータ量が100GBを超えたり、プロビジョニング済みスループットが30,000RU/sを超えたりすると、クロスパーティションクエリやホットパーティションの影響が見えやすくなります。公式記事でも、大きな読み取り中心コンテナーでは、クエリで頻繁に使う等値フィルターに合うパーティションキーを選ぶことが重要とされています。(Microsoft Learn)
パーティションキー選定で見るべき判断基準
パーティションキーは、Azure Cosmos DBの性能、コスト、移行難易度を大きく左右します。選定時は、単に「値の種類が多いか」だけでは不十分です。
値の種類が多いだけでは足りない
良いパーティションキーには、高いカーディナリティが必要です。つまり、値の種類が十分に多く、データとRU消費を分散できる必要があります。
ただし、ランダムGUIDのように値の種類が多くても、アプリケーションのクエリ条件にほとんど登場しない場合、読み取り処理がクロスパーティションクエリになりやすくなります。書き込みは分散できても、読み取りのRU消費とレイテンシが悪化する可能性があります。
クエリパターンと一致しているかを見る
読み取りが多いコンテナーでは、よく使う検索条件とパーティションキーが一致しているかが重要です。
たとえば、ユーザーごとの注文履歴を取得するAPIが中心なら、/userIdや/customerIdは候補になります。一方、管理画面で「注文日」「ステータス」「店舗」「商品カテゴリ」など複数条件で横断検索することが多い場合、単一のパーティションキーだけでは最適化しきれません。
この場合は、通常のパーティションキーだけでなく、合成パーティションキー、階層型パーティションキー、グローバルセカンダリインデックスを検討します。
変更されない値を使う
パーティションキー値は、項目作成後にその場で変更できません。項目を別のパーティションへ移動したい場合は、新しいパーティションキー値を持つ項目を作成し、元の項目を削除する必要があります。この2操作は異なる論理パーティション間でアトミックに実行できないため、業務データでは整合性設計が必要です。(Microsoft Learn)
避けたい例は、後から変わる可能性がある値です。
| 避けたい候補 | 理由 | 代替案 |
|---|---|---|
email | ユーザーが変更する可能性がある | userId |
status | 値の種類が少なく、変更も多い | orderId、customerId、合成キー |
planType | プラン変更で値が変わる | tenantId、tenantId_userId |
country | 値の種類が少なく偏りやすい | 地域以外の高カーディナリティなキー |
数値IDは文字列化も検討する
公式記事では、パーティションキー値には文字列型または数値型を使用できる一方、倍精度数値の境界を超える可能性がある数値は文字列へ変換することが推奨されています。大きなIDを数値として扱うと、言語やJSON処理系によって精度問題が起きる可能性があるためです。(Microsoft Learn)
特に、外部システム由来の長い注文番号、会員番号、決済ID、Snowflake形式のIDなどを扱う場合は、パーティションキーとして使う前に型を確認しましょう。
よくあるアンチパターンと改善策
2026年5月更新で特に実務者が見るべきなのは、パーティションキーのアンチパターンです。MicrosoftDocsの履歴でも、アンチパターンに関するガイダンス追加と文言調整が確認できます。(GitHub)
/idを汎用的に使う
/idをパーティションキーにすると、項目ごとに論理パーティションが分かれるため、書き込み分散やポイント読み取りには向いています。しかし、id以外の条件で検索するクエリが多い場合は、クロスパーティションクエリになりやすくなります。
向いているのは、次のようなワークロードです。
/idが向くケース | /idが向かないケース |
|---|---|
idを指定したポイント読み取りが中心 | 顧客別、日付別、ステータス別の検索が多い |
| 書き込み分散を重視する | 一覧画面や管理画面の絞り込みが多い |
| 項目単位で独立している | 同じユーザーや同じ注文グループをまとめて読む |
「とりあえず/id」は危険です。APIの主要な読み取りパターンを確認し、id以外の検索が多いなら別のキーを検討しましょう。
statusやtypeのような低カーディナリティ項目を使う
status、type、countryのような値の種類が少ない項目をパーティションキーにすると、論理パーティション数が少なくなります。その結果、一部の値にアクセスが集中し、RU消費やデータ量が偏りやすくなります。
たとえば、注文データでstatusをパーティションキーにすると、多くのデータがcompletedやpendingに集中する可能性があります。これはホットパーティションの典型例です。
改善策としては、customerId、orderId、tenantId_userId、storeId_dateのように、より分散しやすく、かつクエリに使いやすいキーを検討します。
高カーディナリティでもクエリに合っていない
値の種類が多いキーでも、クエリで使われなければ読み取り性能の改善にはつながりません。
たとえば、randomGuidをパーティションキーにすれば書き込みは分散できます。しかし、実際の検索が「顧客IDで注文を探す」「テナントIDでログを一覧する」なら、ほとんどの検索がクロスパーティションになります。
この場合は、次の順で検討すると判断しやすくなります。
| 状況 | 検討する設計 |
|---|---|
| 主要クエリが1つの軸に集約できる | 通常のパーティションキー |
| 単一項目では分散と検索条件を両立できない | 合成パーティションキー |
| テナント、ユーザー、セッションなど階層構造が自然にある | 階層型パーティションキー |
| 複数の独立した検索軸があり、単一設計では対応しづらい | グローバルセカンダリインデックス |
パーティションキーの種類と使い分け
公式記事では、通常のパーティションキー、合成パーティションキー、階層型パーティションキー、グローバルセカンダリインデックスが整理されています。(Microsoft Learn)
| 選択肢 | 向いているケース | 注意点 |
|---|---|---|
| 通常のパーティションキー | customerIdやorderIdなど、検索条件と分散を両立できる | 特定顧客や特定テナントに偏るとホットパーティション化する |
| 合成パーティションキー | 単一項目だけでは分散できない書き込み中心ワークロード | 片方の項目だけで検索するとクロスパーティションになりやすい |
| 階層型パーティションキー | テナント、ユーザー、セッションのような階層構造がある大規模データ | 第1階層のカーディナリティが低いと書き込みが詰まりやすい |
| グローバルセカンダリインデックス | 複数の独立したクエリパターンを効率化したい | プレビュー機能であり、追加のRU・ストレージ・最終的一貫性を考慮する |
階層型パーティションキーを使う判断基準
階層型パーティションキーは、パーティションキーを最大3階層まで構成できる機能です。マルチテナント環境でTenantIdだけでは20GB上限に近づく場合や、テナント配下にユーザー、セッションなど自然な階層がある場合に候補になります。公式情報では、階層型パーティションキーにより、論理パーティションキーのプレフィックスが20GBや10,000RU/sを超えるシナリオに対応できると説明されています。(Microsoft Learn)
ただし、第1階層のカーディナリティが低いと、書き込みが一部の物理パーティションに偏る可能性があります。たとえば、テナント数が5社しかない状態でTenantIdを第1階層にすると、特定テナントの大量書き込みがボトルネックになりやすくなります。
グローバルセカンダリインデックスを使う判断基準
グローバルセカンダリインデックスは、ソースコンテナーとは異なるパーティションキーでデータを保持する読み取り専用コンテナーです。ソースコンテナーと自動同期され、別のクエリパターンを効率化できます。(Microsoft Learn)
たとえば、ソースコンテナーをcustomerIdで最適化しているが、管理画面ではorderIdやemailAddressでも高速に検索したい場合、GSIが候補になります。
ただし、GSIは万能ではありません。公式情報では、GSIは最終的一貫性で同期され、独自のパーティションキー、インデックスポリシー、スループット、データモデルを持つとされています。また、GSIコンテナーには追加のストレージとRUが必要です。(Microsoft Learn)
本番採用時は、次の点を確認してください。
| 確認項目 | 理由 |
|---|---|
| プレビュー機能を採用できる運用ルールか | 組織によっては本番利用に承認が必要 |
| 最終的一貫性で問題ないか | 書き込み直後の厳密な即時検索には向かない場合がある |
| GSI側のRUを見積もったか | ソースとは別にRU消費が発生する |
| インデックス対象のプロパティが全項目に存在するか | 欠損値が偏ると論理パーティション上限に近づく可能性がある |
| 置換・削除の追加RUを考慮したか | 更新・削除が多いワークロードではコストに影響する |
既存コンテナーで確認すべき設定とメトリック
管理者や開発者は、今回の情報を読んだだけで終わらせず、既存環境を次の順で確認すると効果的です。
パーティションキーごとのデータ量を確認する
最初に見るべきは、特定の論理パーティションキー値が20GBに近づいていないかです。公式ドキュメントでは、Azure Monitorアラートを使い、論理パーティションキーのストレージが20GB上限に近づいているか監視する方法が紹介されています。例では、20GBの70%である14GBを超えた場合にアラートを発火させる構成が示されています。(Microsoft Learn)
実務では、次のようなルールにしておくと運用しやすくなります。
| しきい値 | 状態 | 推奨アクション |
|---|---|---|
| 10GB未満 | 通常監視 | 月次またはリリース前に確認 |
| 10〜14GB | 注意 | 増加率、対象キー、将来予測を確認 |
| 14GB以上 | 警戒 | 移行、階層型キー、合成キー、データ分離を検討 |
| 18GB以上 | 危険 | 新規書き込み停止リスクを前提に緊急対応を計画 |
診断ログとLog Analyticsを有効化する
論理パーティションキーのサイズ監視には、Diagnostic LogsのPartitionKeyStatisticsログカテゴリを使います。公式手順では、Azure Cosmos DBアカウントで診断ログを有効化し、Log Analyticsワークスペースへ送信する構成が前提です。(Microsoft Learn)
まだ設定していない場合は、次の順で確認します。
| 手順 | 確認内容 |
|---|---|
| 診断設定を確認 | 対象のAzure Cosmos DBアカウントでDiagnostic Logsが有効か |
| ログカテゴリを確認 | PartitionKeyStatisticsを収集しているか |
| 送信先を確認 | Log Analyticsワークスペースに送信されているか |
| アラートを作成 | 14GBなど運用上のしきい値で通知できるか |
| 通知先を確認 | メール、Teams連携、Azure Function、Logic Appsなどに届くか |
クエリがパーティションキーを含んでいるか確認する
読み取り処理では、主要クエリがパーティションキーを含んでいるかを確認します。
たとえば、/customerIdをパーティションキーにしているなら、APIやクエリにWHERE c.customerId = @customerIdのような条件が入っているかを見ます。含まれていない検索が多い場合、物理パーティション数が増えるほどクロスパーティションクエリの負荷が目立ちます。
管理画面やバッチ処理では、横断検索が必要なこともあります。その場合は、単に「クロスパーティションだから悪い」と判断するのではなく、実行頻度、RU消費、レイテンシ、代替設計のコストを比較しましょう。
パーティションキーを変更したい場合の移行方法
Azure Cosmos DBでは、既存コンテナーのパーティションキーをその場で変更できません。変更するには、新しいパーティションキーを持つコンテナーを作成し、データを移動する必要があります。公式記事では、コンテナーコピージョブやグローバルセカンダリインデックスが選択肢として示されています。(Microsoft Learn)
コンテナーコピーを使う場合
コンテナーコピーは、既存コンテナーから別コンテナーへデータをコピーするための機能です。公式情報では、パーティションキーの変更、スループットの粒度変更、ユニークキー更新、コンテナー名変更、新しいコンテナーでのみサポートされる機能の採用などに利用できるとされています。(Microsoft Learn)
移行時の基本的な流れは次のとおりです。
| フェーズ | 作業内容 | 注意点 |
|---|---|---|
| 設計 | 新しいパーティションキー、インデックスポリシー、TTL、ユニークキーを決める | 既存設定をそのままコピーすればよいとは限らない |
| 準備 | 移行先コンテナーを作成する | RU、オートスケール、リージョン設定も確認 |
| コピー | コンテナーコピージョブを実行する | オンラインコピーかオフラインコピーかで手順が変わる |
| 検証 | 件数、代表データ、クエリ結果、RU消費を比較する | データ欠損や重複を確認 |
| 切り替え | アプリケーションの接続先を変更する | ロールバック手順を用意する |
| 監視 | 429、レイテンシ、RU消費、エラー率を監視する | 切り替え直後は負荷傾向が変わる |
オフラインコピーでは、コピー開始前にソースコンテナーへの操作を停止することが強く推奨されています。コピー中にソース側で削除や更新を続けると、移行先で重複や欠損が起きる可能性があるためです。(Microsoft Learn)
オンラインコピーを使う場合でも、前提条件やRU増加に注意が必要です。公式情報では、オンラインコピーの前提として継続的バックアップや変更フィードモードの設定が示されており、ソースアカウントの書き込み操作に追加RUが発生する旨も説明されています。(Microsoft Learn)
自前移行を行う場合
アプリケーション側でデータを読み出して新コンテナーへ書き込む方法もあります。この場合は、単純な一括コピーではなく、以下を設計しておく必要があります。
| 項目 | 確認内容 |
|---|---|
| 二重書き込み | 移行期間中の新旧コンテナーの整合性をどう保つか |
| 再実行性 | 途中失敗しても安全に再開できるか |
| 削除反映 | 削除済みデータを移行先に残さない仕組みがあるか |
| 順序性 | 更新順序が業務上問題にならないか |
| 切り戻し | 切り替え後に問題が出た場合、旧コンテナーへ戻せるか |
| コスト | 移行中の読み取りRU、書き込みRU、ストレージ増加を見積もったか |
パーティションキー変更は、単なるスキーマ変更ではなく、データ配置とアクセスパターンの変更です。移行計画では、アプリケーション改修、運用監視、コスト試算まで含めて判断しましょう。
展開前に失敗しやすいポイント
Azure Cosmos DBのパーティション設計では、開発環境では見えなかった問題が本番負荷で表面化しがちです。展開前に、次の失敗パターンをつぶしておきましょう。
| 失敗しやすいポイント | 何が起きるか | 予防策 |
|---|---|---|
| テストデータが均等すぎる | 本番の偏りを再現できず、ホットパーティションを見逃す | 大口顧客、特定日、特定地域に偏ったデータで負荷試験する |
| 一覧画面のクエリを軽視する | 管理画面だけRU消費が大きくなる | 主要画面ごとにクエリとRUを測る |
| パーティションキー変更を軽く見る | 移行作業が大きくなり、停止時間が伸びる | 初期設計時に変更不能性を前提にレビューする |
| GSIを同期済みテーブルのように扱う | 書き込み直後の検索結果にズレが出る可能性がある | 最終的一貫性で許容できる用途に限定する |
| 階層型キーの第1階層が少なすぎる | 書き込みが一部に集中する | 第1階層の値数と負荷分布を確認する |
statusやtypeをキーにする | 値が少なく、ホットパーティションになりやすい | 高カーディナリティでクエリに合うキーを選ぶ |
新規設計時の実用的な決め方
新しくコンテナーを設計する場合は、先にパーティションキー名を決めるのではなく、アクセスパターンから逆算します。
最初に書き出すべき情報
| 確認項目 | 例 |
|---|---|
| 主要な読み取り条件 | customerIdで注文一覧、tenantIdでユーザー一覧 |
| 主要な書き込み単位 | 注文作成、ログ追加、セッションイベント追加 |
| データが増える軸 | 顧客、テナント、デバイス、日付 |
| 偏りやすい軸 | 大口顧客、人気商品、大規模テナント |
| トランザクション範囲 | 同一注文内、同一ユーザー内、同一テナント内 |
| 将来の検索要件 | 管理画面、分析、全文検索、ベクトル検索 |
この情報を整理したうえで、候補キーを比較します。
| ワークロード例 | 候補キー | 判断 |
|---|---|---|
| ユーザーごとのプロフィール参照 | /userId | 読み取り条件と一致しやすい |
| 注文履歴API | /customerId | 顧客単位の検索に強いが、大口顧客の偏りを確認 |
| 大量の注文書き込み | /customerId_orderMonth | 書き込み分散に有効。ただし顧客単独検索は工夫が必要 |
| マルチテナントのイベントログ | /tenantId、または階層型/tenantId→/userId→/sessionId | テナントごとの成長差を確認 |
| IoTテレメトリ | /deviceId_dateBucket | 特定デバイスや時間帯の集中に注意 |
| 複数軸の検索が必要な業務アプリ | ソースは主要キー、別軸はGSIを検討 | プレビュー制約とコストを確認 |
管理者と開発者が今すぐ確認すべきチェックリスト
既存のAzure Cosmos DB環境がある場合は、次の順で確認すると、パーティション設計のリスクを短時間で洗い出せます。
| チェック | 確認内容 |
|---|---|
| コンテナー一覧 | 重要コンテナー、データ量、RU設定、API種別を整理する |
| パーティションキー | 現在のパーティションキーパスと値の分布を確認する |
| データ量 | 論理パーティションキーごとのサイズが20GBに近づいていないか見る |
| RU消費 | 特定キーにリクエストが集中していないか見る |
| クエリ | 主要クエリにパーティションキー条件が含まれているか確認する |
| トランザクション | ストアドプロシージャやトリガーが複数パーティションを前提にしていないか確認する |
| 監視 | Diagnostic Logs、Log Analytics、Azure Monitorアラートを設定する |
| 移行計画 | キー変更が必要な場合、新コンテナー作成と切り替え手順を用意する |
| 新機能検討 | 階層型パーティションキーやGSIが要件に合うか評価する |
| 費用見積もり | 移行中、GSI利用時、コピー時の追加RUとストレージを見積もる |
まとめ：まずはパーティションキーの偏りを確認する
Azure Cosmos DBの「Partitioning and horizontal scaling」で重要なのは、パーティション分割の仕組みを知ること自体ではなく、自社のコンテナーがその仕組みに合った設計になっているかを確認することです。
特に、次の3つを優先して確認してください。
- 既存コンテナーのパーティションキー値ごとのデータ量が20GBに近づいていないか
- 主要クエリがパーティションキーを含み、不要なクロスパーティションクエリを増やしていないか
/id、status、ランダムGUIDなど、便利に見えるが実運用で不利になりやすいキーを選んでいないか
問題が見つかった場合は、いきなり移行するのではなく、通常のパーティションキー、合成パーティションキー、階層型パーティションキー、グローバルセカンダリインデックス、コンテナーコピーのどれが最もリスクとコストを抑えられるかを比較しましょう。Azure Cosmos DBのスケーリングは自動で行われますが、スケールしやすいデータ配置を作る責任は設計側にあります。
コメント