Azure Cosmos DBのパーティションキー変更ガイド｜4つの方法と注意点【2026年7月】

Azure Cosmos DBのパーティションキーを変更したいものの、「既存コンテナーをそのまま更新できるのか」「停止時間や追加コストはどの程度か」と判断に迷うケースは少なくありません。

結論から言うと、Azure Cosmos DBのパーティションキーは、既存コンテナー内で直接書き換えることはできません。変更する場合は、新しいパーティションキーを設定したコンテナーへデータを移し、アプリケーションの接続先を切り替えます。

Microsoftが2026年7月6日に公開した公式ガイドでは、Azureポータルの「Change Partition Key」、コンテナーコピージョブ、独自移行、グローバルセカンダリインデックスの使い分けが整理されました。対応が必要なのは、ホットパーティションやクロスパーティションクエリなど、現在のパーティションキーが実際に問題を起こしている環境です。すべての利用者に変更を求める更新ではありません。(Microsoft for Developers)

Azure Cosmos DBのパーティションキー変更ガイドで明確になったこと

Azure Cosmos DBのパーティションキーは、データをどの論理パーティションへ配置するかを決める項目です。データ量だけでなく、リクエストの分散、クエリのルーティング、RU消費量、トランザクション範囲にも影響します。

Microsoftの2026年7月6日のガイドで特に明確になったのは、「何を解決したいかによって選択肢が異なる」という点です。

解決したい問題	主な選択肢	データ移行	適したケース
書き込みの集中やデータ分布を改善したい	AzureポータルのChange Partition Key	必要	操作負担を抑えて移行したい
移行をスクリプト化したい	コンテナーコピージョブ	必要	CLIや自動化パイプラインから制御したい
データ変換や複雑な切り替えが必要	独自移行	必要	大規模移行やスキーマ変換を伴う
別のキーで効率よく検索したい	グローバルセカンダリインデックス	元コンテナーの移行は不要	読み取りクエリだけを最適化したい

重要なのは、最初の3つがいずれも「新しいコンテナーへの移行」であることです。既存コンテナーのパーティションキーが書き換えられるわけではありません。

一方、グローバルセカンダリインデックスは、元コンテナーを維持したまま、別のパーティションキーを持つ読み取り専用コンテナーを追加する仕組みです。(Microsoft for Developers)

2026年7月6日の情報は新機能発表ではなく「選び方」の更新

Azure Cosmos DB for NoSQLの「Change Partition Key」機能自体は、2026年6月2日に一般提供が発表されています。Azureポータルからオンラインまたはオフラインでデータをコピーし、新しいコンテナーへ切り替えられる機能です。(Microsoft for Developers)

2026年7月6日の公式情報は、一般提供されたポータル機能だけを紹介するものではありません。次の選択肢を横断的に比較し、ワークロードに合う方法を判断できるようにした実務的なガイドです。

AzureポータルのChange Partition Key
コンテナーコピージョブの直接利用
Bulk、Azure Data Factory、Sparkなどを使った独自移行
グローバルセカンダリインデックス

したがって、今回の情報を「既存のパーティションキーをその場で変更できるようになった」と理解するのは正確ではありません。

対応要否は「書き込み」と「読み取り」のどちらが問題かで判断する

パーティションキー変更を検討するときは、最初に問題を2種類に分けます。

書き込みやデータ分布に問題がある場合

次のような状況では、データを新しいパーティションキーで再配置する必要があります。

特定のパーティションキー値に書き込みが集中している
一部の論理パーティションで429エラーが頻発している
特定テナントや顧客のデータだけが急増している
論理パーティションが20GBの上限に近づいている
新しいデータモデルでは、現在のキーで要求を分散できない

この場合、グローバルセカンダリインデックスを追加しても、元コンテナーの書き込み先は変わりません。ホットパーティションを解消するには、Change Partition Key、コンテナーコピージョブ、独自移行のいずれかを選びます。

読み取りクエリだけに問題がある場合

次のような状況では、必ずしもパーティションキーを変更する必要はありません。

パーティションキー以外のプロパティで検索する機会が増えた
クロスパーティションクエリのRU消費量が大きい
新しい検索パターンを追加したい
既存の書き込み分散には問題がない
元コンテナーの移行やアプリ改修を避けたい

たとえば、元コンテナーが/customerIdで分割されている一方、メールアドレス検索が増えた場合は、/emailAddressをパーティションキーにしたグローバルセカンダリインデックスが候補になります。

Azure Cosmos DBのパーティションキーを変更する4つの方法

AzureポータルのChange Partition Keyを使う

最も操作負担が少ない方法です。

Azureポータルで対象コンテナーを開き、次の順に進みます。

Data Explorerを開く
対象コンテナーを選択する
「Scale & Settings」を開く
「Partition Keys」タブを選択する
「Change」を選択する
オンラインまたはオフラインを選ぶ
新しいコンテナーを作成するか、同じデータベース内の既存コンテナーを選ぶ
コピー完了後、アプリケーションの接続先を変更する

ポータルから新しいコンテナーを作成した場合、パーティションキーと一意キーを除く構成は、原則として移行先へ複製されます。パーティションキーと一意キーについては、移行先用に設定し直す必要があります。(Microsoft Learn)

オンラインモードでは、コピー中も元コンテナーへの書き込みを継続できます。ただし、最終的な「Complete」処理と接続先切り替えの直前には、一時的に書き込みを停止し、残りの変更を反映させる必要があります。

そのため、「完全な無停止移行」ではなく、大量コピー中の停止時間を短縮できる方式と考えるのが適切です。

コンテナーコピージョブを直接利用する

コンテナーコピージョブは、ポータルのChange Partition Key機能でも使用されているコピー基盤です。Azure CLIからジョブを作成、監視、完了できるため、次のような用途に向いています。

移行手順をスクリプト化したい
複数環境で同じ移行を実施したい
CI/CDや運用ツールに組み込みたい
コピー先のスループットやインデックスポリシーを細かく設定したい
別アカウントへコピーしたい

別アカウントへのコピーでは、コピー先アカウントのIDに対し、コピー元コンテナーを読み取るための権限設定が必要です。

注意したいのは、ポータルのChange Partition Keyは一般提供されていますが、コンテナーコピージョブを直接利用するMicrosoft Learnページは、2026年5月18日時点で「preview」と表記されている点です。ポータル経由とCLIによる直接利用では、提供状態やサポート条件が異なる可能性があるため、本番導入前に最新のドキュメントを確認してください。(Microsoft Learn)

独自の移行処理を構築する

次の条件に当てはまる場合は、独自移行が候補になります。

移行中にJSON構造を変更したい
不要なデータを除外したい
複数コンテナーのデータを統合したい
ポータル機能やコンテナーコピージョブの上限を超える
切り替えやロールバックを完全に自社で制御したい
独自の検証処理や監査処理を組み込みたい

公式ガイドでは、主に次の方法が示されています。

.NET SDKのBulk機能による一括書き込み
Azure Data Factoryによるコピー
Azure Cosmos DB Spark Connector
Change Feedによる差分同期

最初に大量データを移し、その後Change Feedでコピー中に発生した更新を追従する構成が一般的です。

ただし、既定のLatest versionモードでは削除やTTLによる期限切れを取得できません。削除も含めて反映する場合は、継続的バックアップと「All versions and deletes」モードが必要です。(Microsoft for Developers)

独自移行は自由度が高い一方、再試行、重複排除、差分同期、エラー処理、切り替え、ロールバックをすべて実装する必要があります。

グローバルセカンダリインデックスを使う

グローバルセカンダリインデックス（GSI）は、元コンテナーとは異なるパーティションキーを持つ、読み取り専用のコンテナーです。元データの変更は自動的に同期されます。

たとえば、元コンテナーを/customerIdで分割し、GSIを/emailAddressで分割すれば、メールアドレス検索をGSI側の単一パーティションクエリとして実行できます。

GSIは2026年6月2日に一般提供が発表されています。次のようなワークロードに適しています。

複数の独立した検索パターンがある
元コンテナーの移行を避けたい
読み取り処理をトランザクション処理から分離したい
ベクトル検索や全文検索用のインデックスを別コンテナーへ分離したい

ただし、GSIには次の注意点があります。

元コンテナーとは結果が即時一致せず、結果整合性になる
GSI用のストレージ料金とRU料金が発生する
GSIコンテナーはオートスケールスループットを使用する
元コンテナーの置換と削除では、基本書き込み料金に対して50～100％の追加RUが発生する
新規作成操作には追加RUの影響がない
元コンテナーの書き込み分布やホットパーティションは改善しない
GSIの定義クエリは作成後に変更できない

読み取りクエリの最適化だけが目的なら有力ですが、書き込み負荷を分散したい場合はデータの再パーティションが必要です。(Microsoft for Developers)

Change Partition Keyの主な提供条件

導入前には、対象コンテナーとアカウントが条件を満たしているか確認します。

確認項目	主な条件・注意点
対象API	Azure Cosmos DB for NoSQL
コンテナーサイズ	4TB未満
プロビジョニング済みスループット	100万RU/s未満
対応リージョン	公式ドキュメントに掲載されたリージョンのみ
日本リージョン	Japan East、Japan Westが対応一覧に掲載
アカウント機能	Merge partitionが有効なアカウントは非対応
オンラインコピー	継続的バックアップとAll versions and deletes change feedが必要
オフラインコピー	コピー開始前に元コンテナーへの操作を停止する
完了時間	ベストエフォートであり、完了時間のSLAはない
大規模コンテナー	4TB以上または100万RU/s以上はMicrosoftサポートへの相談が必要

リージョンや上限は変更される可能性があります。実施時点の公式ドキュメントで再確認してください。(Microsoft Learn)

オンラインコピーとオフラインコピーの違い

項目	オンラインコピー	オフラインコピー
コピー中の書き込み	継続可能	原則停止
主な用途	停止時間を短くしたい本番環境	書き込みを止められる環境
必要なバックアップ	継続的バックアップ	オンライン固有の前提は不要
Change Feed	All versions and deletes	Latest versionモードを利用
最終切り替え	一時的な書き込み停止が必要	コピー完了後に切り替え
RUへの影響	ソース側の書き込みRUが増加	コピー先書き込みRUが発生
データ欠落リスク	正しく完了処理すれば抑えられる	コピー中に更新すると欠落や重複の可能性

オンラインコピーを有効にすると、公式ドキュメント上、ソースアカウントの書き込み操作には通常の2倍のRUが課金されます。対象コンテナーだけでなく、同じアカウント内の書き込みワークロード全体への影響を見積もることが重要です。(Microsoft Learn)

オフラインコピーでは、ジョブ開始後も元コンテナーを更新すると、更新や削除がコピー先へ反映されない可能性があります。元データへのアクセスを停止できない場合は、オフラインモードを安易に選ばないでください。

新しいパーティションキーを決める前の確認ポイント

移行機能が使えることと、新しいパーティションキーが適切であることは別問題です。設計が不十分なまま移行すると、別のホットパーティションやクロスパーティションクエリを生む可能性があります。

値の種類が十分に多いか

status、type、countryのように値の種類が少ないプロパティは、少数の論理パーティションへ負荷が集中しやすくなります。

新しいキーには、原則として次の特徴が必要です。

値の種類が多い
データ量を均等に分散できる
RU消費量を均等に分散できる
頻繁に実行するクエリの検索条件に含まれる
アイテム作成後に変更されない
多くのアイテムで欠損やnullにならない

高カーディナリティであっても、クエリでまったく使用しないランダムIDを選ぶと、読み取りの多くがクロスパーティションクエリになる場合があります。分散性能と検索パターンの両方で評価してください。(Microsoft Learn)

新しいパーティションキーとidの組み合わせが重複しないか

Azure Cosmos DBでは、アイテムはパーティションキー値とidの組み合わせで一意になります。

たとえば、元のパーティションキーが/departmentで、次の2件が存在するとします。

{
  "id": "101",
  "employeeName": "Taro",
  "department": "Sales"
}

{
  "id": "101",
  "employeeName": "Taro",
  "department": "Finance"
}

元の構成では、departmentが異なるため両方を保存できます。しかし、新しいパーティションキーを/employeeNameにすると、どちらもemployeeName = Taroかつid = 101となり、移行先で衝突します。

本番移行前に、新しいパーティションキーとidの重複を集計してください。重複が見つかった場合は、idの再設計やデータ変換を伴う独自移行が必要になる可能性があります。(Microsoft Learn)

論理パーティションが20GBを超えないか

通常のパーティションキーでは、1つの論理パーティションに保存できるデータは最大20GBです。

たとえば、/tenantIdをパーティションキーにすると、1社の大規模テナントだけで20GBを超える可能性があります。その場合は、TenantId、UserId、SessionIdのような階層型パーティションキーを検討します。

階層型パーティションキーでは、最大3階層まで指定できます。新しいコンテナーを作成する移行は、作成時にしか設定できない機能を採用する機会でもあります。(Microsoft Learn)

トランザクション範囲が変わっても問題ないか

Azure Cosmos DBのストアドプロシージャやトリガーによるトランザクションは、単一の論理パーティション内に限定されます。

パーティションキーを変更すると、これまで同じパーティションに存在したアイテムが別々のパーティションへ分かれる可能性があります。複数アイテムをまとめて更新する処理がある場合は、移行前にトランザクション境界を確認してください。

コピー開始前に確認すべきコストとデータ仕様

コピー先のRU/sを十分に確保する

Microsoftは、コンテナーコピージョブの進行速度を確保するため、コピー先のスループットをコピー元の少なくとも2倍に設定することを推奨しています。

コピー中だけ一時的にRU/sを引き上げ、完了後に通常値へ戻す方法もあります。ただし、オートスケールと手動スループットでは費用の考え方が異なるため、事前に見積もりが必要です。(Microsoft Learn)

TTLの残り時間は引き継がれない

Time to Liveが設定されている場合、コピー時点で期限切れになっていないアイテムは、コピー先でTTLのカウントを最初から開始します。

たとえば、TTLが30日で、コピー元では残り1日だったアイテムでも、コピー先では新たに30日残る状態になる可能性があります。セッションデータ、一時キャッシュ、監査ログなどでは、保存期間やストレージ料金に影響するため注意が必要です。(Microsoft Learn)

オンラインコピー中のid変更に注意する

オンラインコピー中に元アイテムのidを変更すると、コピー先では変更前と変更後が別アイテムとして保存される場合があります。

実際にはidを直接更新できないため、削除と新規作成によって変更する実装が該当します。移行中はidを変える処理を停止するか、コピー後の重複検証を行ってください。

コピー完了時間を固定スケジュールで見積もらない

コンテナーコピージョブはベストエフォートで実行され、完了時間に関するSLAはありません。また、同一アカウント内で複数のジョブを作成しても、ジョブは順番に処理されます。

「2時間後に必ず切り替える」といった固定スケジュールではなく、コピー進捗を条件に切り替え判断を行う運用が必要です。

本番移行で使える実施手順

移行前

429エラー、Normalized RU Consumption、クエリRU、レイテンシを確認する
問題が書き込み分布か読み取りクエリかを分類する
新しいパーティションキー候補ごとのデータ件数と容量を集計する
新しいキーとidの重複を確認する
欠損値、null、異常に大きいキー値がないか確認する
対象リージョン、コンテナー容量、RU/s、バックアップモードを確認する
TTL、一意キー、インデックスポリシー、階層型パーティションキーの設定を決める
非本番環境で同じ手順を検証する

コピー中

コピー元とコピー先のRU消費量を監視する
429エラーやコピーエラーを監視する
オンラインコピーではアカウント全体の書き込みRU増加を確認する
コピー件数と元コンテナーの件数を比較する
アプリケーションからコピー先へのテストクエリを実行する

切り替え時

コピー元への書き込みを停止する
オンラインジョブの「Complete」を実行する
残りの変更がコピー先へ反映されたことを確認する
アプリケーションのコンテナー名や設定値を変更する
段階的にトラフィックをコピー先へ切り替える
問題が起きた場合に元へ戻せる状態を維持する

切り替え後

主要クエリのRUとレイテンシを移行前と比較する
パーティション別のデータ量と要求量を確認する
429エラーが減少したか確認する
TTL、一意キー、インデックスの動作を確認する
件数だけでなく、サンプルデータや業務上重要な集計値を照合する
十分な確認期間を置いてから元コンテナーを削除する

失敗しやすいポイント

「一般提供だから制約なく使える」と考える

Change Partition Keyは一般提供されていますが、コンテナー容量、RU/s、リージョン、アカウント機能などに制約があります。大規模環境では、Microsoftサポートへの相談や独自移行が必要です。

「オンラインなら一切停止しなくてよい」と考える

オンラインコピー中は書き込みを続けられますが、最終同期と接続先切り替えでは短時間の停止が必要です。アプリ側に書き込み停止機能やメンテナンスモードがない場合は、先に実装しておく必要があります。

「コンテナー設定はすべて自動で同じになる」と考える

ポータルが新しいコンテナーを作成する場合でも、パーティションキーと一意キーは再設定が必要です。既存コンテナーをコピー先に選ぶ場合は、スループット、インデックス、TTLなども個別に照合してください。

「GSIを追加すればホットパーティションも直る」と考える

GSIは読み取りパターンを最適化する機能です。元コンテナーへの書き込み先やデータ分布は変わりません。書き込み側のホットパーティションには、データの再パーティションが必要です。

コピー件数だけで移行成功と判断する

コピー件数が一致していても、TTLの再カウント、idの重複、削除データの未反映、インデックスポリシーの違いが残る可能性があります。

件数に加え、次の項目を検証してください。

主要な集計結果
業務上重要なアイテム
削除済みデータの有無
TTL対象データ
一意キー違反
クエリ結果と並び順
RU消費量とレイテンシ

対応要否を判断するための結論

今回のMicrosoft公式ガイドは、Azure Cosmos DB利用者に一律の変更作業を求めるものではありません。現在のパーティションキーがワークロードに合わなくなった場合に、適切な解決策を選ぶための情報です。

判断は次の順で行うと迷いにくくなります。

書き込み分布が問題なら、Change Partition Keyかデータ移行を検討する
読み取りのクロスパーティションクエリだけが問題なら、GSIを検討する
操作負担を抑えたいなら、Azureポータルを使う
自動化したいなら、コンテナーコピージョブの提供状態を確認する
データ変換や大規模移行が必要なら、独自移行を設計する

最初に実施すべきことは、すぐに移行ジョブを開始することではありません。対象コンテナーのサイズ、RU/s、リージョン、バックアップモード、ホットパーティション、クロスパーティションクエリを確認し、問題が書き込み側と読み取り側のどちらにあるかを特定してください。

そのうえで新しいパーティションキー候補を非本番環境で検証し、コスト、停止時間、データ整合性、ロールバック手順まで準備してから本番移行へ進むことが重要です。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

Azure Cosmos DBのパーティションキー変更ガイド｜4つの方法と注意点【2026年7月】

Azure Cosmos DBのパーティションキー変更ガイドで明確になったこと

2026年7月6日の情報は新機能発表ではなく「選び方」の更新