Azure Cosmos DB for NoSQLで「パーティションキーを変えたいが、移行が大変そう」と悩んでいた管理者・開発者にとって、今回のGAは実務上かなり大きな変更です。結論から言うと、Azure portal上で既存コンテナーのデータを新しいパーティションキーのコンテナーへコピーし、オンラインまたはオフラインで移行できるようになりました。従来のように移行用コード、Change Feed処理、切り替え手順を一から組む負担を減らせる一方、アプリの接続先変更、RU消費、idと新パーティションキーの重複、短時間の書き込み停止計画は引き続き重要です。
なお、この更新は名前に「NoSQL API」とある通り、Azure SQL DatabaseやAzure SQL Managed Instanceの機能ではありません。Azureのデータベース更新として一緒に確認されることがありますが、対象はAzure Cosmos DB for NoSQLのコンテナーです。
Azure Cosmos DBのパーティションキー変更GAで何が変わったのか
Microsoftは2026年6月、Azure Cosmos DB for NoSQLの「Change Partition Key」を一般提供として案内しました。Azure Cosmos DB Blogでは、Azure portalからコンテナーを再パーティション化でき、オンラインコピーではソースコンテナーへの書き込みを止めずに近い形で移行を進められると説明されています。(Microsoft for Developers)
今回のポイントは、「既存コンテナーのパーティションキーそのものを書き換える」というより、新しいパーティションキーを持つ宛先コンテナーへデータをコピーし、アプリケーションを切り替える仕組みだと理解するのが正確です。Microsoft Learnでも、パーティションキー変更は新しい宛先コンテナーの作成、または同一データベース内の既存コンテナー選択を伴うと説明されています。(Microsoft Learn)
管理者や開発者にとっての主な変化は、次の通りです。
| 変更点 | 実務上の意味 |
|---|---|
| Azure portalから変更ジョブを開始できる | 独自の移行ツールや一時的な同期処理を作る負担を減らせる |
| オンライン／オフラインコピーを選べる | 業務停止を最小化する移行と、停止前提の単純な移行を選択できる |
| ソースから宛先へContainer copy jobsでデータをコピーする | 移行中のRU消費、進捗監視、切り替え計画が必要 |
| 宛先コンテナーへアプリを切り替える | 接続設定、コンテナー名、SDK実装、IaC定義の見直しが必要 |
| GAとして利用可能になった | 本番環境で検討しやすくなったが、制限事項の確認は必須 |
特に重要なのは、「ボタンを押せば完全に自動で終わる機能」ではない点です。コピーの開始と監視は簡単になりますが、最終的なアプリケーション切り替え、検証、旧コンテナーの扱いは利用者側で計画する必要があります。
なぜパーティションキー変更が重要なのか
Azure Cosmos DBでは、パーティションキーがデータ分散、クエリルーティング、RU消費、スケーラビリティに直接影響します。Microsoftのドキュメントでも、パーティションキーの選択はアプリケーション性能に影響する重要な判断だと説明されています。(Microsoft Learn)
最初は問題なかった設計でも、サービス成長後に次のような問題が出ることがあります。
| よくある問題 | 例 | 起きる影響 |
|---|---|---|
| ホットパーティション | 一部のテナントやユーザーにアクセスが集中する | レート制限、遅延、RUの無駄が増える |
| クロスパーティションクエリ増加 | statusやcreatedAtだけで検索する画面が増える | クエリRUとレイテンシが上がる |
| 論理パーティションの肥大化 | 1テナントのデータが想定以上に増える | 論理パーティション上限への接近 |
| スキーマ・機能変更 | 新機能で検索軸が変わる | 既存キーが実態に合わなくなる |
たとえば、SaaSで /tenantId をパーティションキーにしていた場合、小規模テナントが多い間は安定します。しかし、大口顧客だけデータ量やアクセス量が突出すると、そのテナントの論理パーティションに負荷が偏ります。この場合、階層型パーティションキーや合成キーを検討する価値があります。
一方で、単純に /id に変えればよいわけでもありません。/id は点読み取りには強い反面、顧客別・期間別・ステータス別の検索が多いアプリではクロスパーティションクエリが増えやすくなります。変更前に「どのクエリを最も安く、速くしたいのか」を決めることが重要です。
対象となる環境と影響範囲
この機能の対象は、Azure Cosmos DB for NoSQLのコンテナーです。Azure SQL Database、Azure SQL Managed Instance、SQL Server on Azure VMのパーティション設計を変更する機能ではありません。
影響を受ける主な担当者は次の通りです。
| 担当者 | 確認すべきこと |
|---|---|
| Azure管理者 | リージョン対応、権限、RU、バックアップ、サポート要否、移行時間帯 |
| アプリ開発者 | 接続先コンテナー、SDKのパーティションキー指定、クエリ、エラーハンドリング |
| SRE／運用担当 | 監視、アラート、切り戻し、書き込み停止時間、移行中のRU増加 |
| データ設計担当 | 新パーティションキーの分散、クエリ適合性、idとの一意性 |
| セキュリティ担当 | アクセス制御、監査ログ、旧コンテナーの保持・削除ルール |
特に本番環境では、アプリケーションがコンテナー名を設定ファイルや環境変数で持っているか、コードに直接埋め込んでいるかを確認してください。移行作業よりも、切り替え時の設定漏れで障害になるケースの方が現実的です。
オンラインモードとオフラインモードの違い
パーティションキー変更では、データコピーの方法としてオンラインとオフラインを選べます。どちらが優れているかではなく、システムの稼働要件によって選びます。
| 項目 | オンラインモード | オフラインモード |
|---|---|---|
| 移行中の書き込み | ソースへの継続書き込みを前提にしやすい | 原則としてソース操作を止める |
| ダウンタイム | 最終切り替え時に短時間の停止を計画 | コピー中は停止時間が長くなりやすい |
| 運用の複雑さ | 高い。最終同期と切り替え管理が必要 | 比較的低い |
| 向いているケース | 24時間稼働、停止許容が小さいサービス | 夜間停止できる社内システム、小規模環境 |
| 注意点 | 最終的に書き込み停止とComplete操作が必要 | コピー中の更新・削除が欠落や重複の原因になり得る |
オンラインコピーでは、Microsoft Learn上で継続的バックアップと「all versions and deletes change feed mode」が前提として説明されており、ソースアカウントでの書き込み操作に追加RUが発生する点にも注意が必要です。(Microsoft Learn)
一方、オフラインコピーでは、コピー開始前にソースコンテナーへの操作を停止することが強く推奨されています。コピー中に更新や削除を続けると、宛先コンテナーでデータ欠落や重複が起きる可能性があります。(Microsoft Learn)
Azure portalでの基本的な移行手順
Azure portalでの作業はシンプルになりましたが、本番移行では事前準備が成否を分けます。大まかな流れは次の通りです。
| 手順 | 作業内容 | 確認ポイント |
|---|---|---|
| 事前調査 | 現在のパーティションキー、データ量、RU、主要クエリを確認 | ホットパーティション、クロスパーティションクエリ、論理パーティションサイズ |
| 新キー設計 | 新しいパーティションキーを決める | 高カーディナリティ、値の安定性、クエリとの一致 |
| 検証環境でテスト | 本番に近いデータでコピーを試す | コピー時間、RU消費、エラー、アプリ動作 |
| portalでジョブ作成 | Data Explorerから対象コンテナーを選び、Partition KeysタブでChangeを選択 | 宛先コンテナー、オンライン／オフラインモード |
| コピー監視 | ジョブ進捗とコピー済みドキュメント数を確認 | RU、エラー、遅延、スロットリング |
| 切り替え | アプリの接続先を新コンテナーへ変更 | 書き込み停止、Complete操作、設定反映 |
| 移行後検証 | 読み書き、主要クエリ、監視メトリックを確認 | RU低下、レイテンシ改善、データ件数 |
| 旧環境整理 | 旧コンテナーの保持・削除を判断 | ロールバック期限、監査、コスト |
Microsoftの手順では、Azure Cosmos DBアカウントのData Explorerから対象コンテナーを選択し、Scale & Settings配下のPartition KeysタブでChangeを選ぶ流れが示されています。(Microsoft for Developers)
管理者が事前に確認すべき設定と制限
GAになったとはいえ、すべてのコンテナーで無条件に使えるわけではありません。Microsoft Learnでは、パーティションキー変更にはいくつかの制限が示されています。たとえば、既定ではコピー処理用にサーバーサイドのコンピュートが割り当てられ、1,000,000 RU/s以上、または4TB超のコンテナーではMicrosoftサポートへの相談が必要とされています。(Microsoft Learn)
移行前に、少なくとも次を確認してください。
| 確認項目 | 見るべき理由 |
|---|---|
| コンテナーのデータ量 | コピー時間、制限、メンテナンス時間に影響する |
| プロビジョニングRU／Autoscale設定 | コピー中のスロットリングやアプリ性能劣化を防ぐ |
| 対応リージョン | Container copy jobsのサポート状況はリージョン確認が必要 |
| Merge partition機能の有無 | 対象外の構成に該当しないか確認する |
| バックアップ設定 | オンラインコピーの前提条件や復旧計画に関係する |
| TTL設定 | 宛先コンテナーでTTLの挙動を再確認する |
| 権限 | portal操作、コンテナー作成、設定変更、監視に必要な権限を確認する |
| ターゲットスループット | Microsoft Learnではコピー速度要因としてソース・ターゲットのスループットが挙げられている |
Container copy jobsでは、コピー速度はソース・ターゲットのスループット設定やサーバーサイドコンピュートの影響を受けます。また、ターゲットコンテナーのスループットをソースの少なくとも2倍にすることが推奨されています。(Microsoft Learn)
本番環境では、移行時間だけでなく「通常トラフィックとコピー処理が同じ時間帯に重なるとどうなるか」を必ず見積もってください。昼間のピーク時間に実行すると、コピーが進まないだけでなく、アプリの通常処理も429エラーの影響を受けやすくなります。
開発者が見直すべき実装ポイント
パーティションキーを変えると、アプリケーション側の実装にも影響します。特にNoSQL APIでは、読み取り・更新・削除時にパーティションキーを指定しているコードが多いため、単に接続先を変えるだけでは不十分な場合があります。
見直すべき代表例は次の通りです。
| 実装箇所 | 確認内容 |
|---|---|
| SDKのReadItem／ReplaceItem／DeleteItem | 新しいパーティションキー値を正しく渡しているか |
| クエリ条件 | 新キーをWHERE句に含められるか |
| APIレスポンス | 新キー候補の値が欠落していないか |
| バッチ処理 | 旧パーティションキー前提の並列化になっていないか |
| キャッシュ | コンテナー名やパーティションキー値をキャッシュしていないか |
| IaC | Bicep、Terraform、ARM Templateなどの定義が新構成と一致しているか |
| 監視 | RU、429、レイテンシ、失敗率を新コンテナーで取れているか |
たとえば、現在 /tenantId をキーにしていて、新たに /tenantId と /userId の階層型パーティションキーを採用する場合、アプリ側でアイテム作成時に両方の値が確実に入るようにする必要があります。古いイベントデータや移行前のレコードに userId がないと、移行後のクエリや書き込みで想定外の動作になります。
新しいパーティションキーの選び方
変更機能が使えるようになったからといって、安易に何度も変える設計は避けるべきです。パーティションキーの変更は依然としてデータ移行であり、コストとリスクを伴います。
新しいパーティションキーは、次の観点で評価します。
| 判断基準 | 良い例 | 避けたい例 |
|---|---|---|
| 値の種類が多い | tenantId + userId、customerId、deviceId | status、type、countryのみ |
| アクセスパターンに合う | よく使う検索条件に含まれる | ほとんど検索で使わないGUID |
| 値が変わりにくい | 顧客ID、デバイスID | ステータス、部署名、表示名 |
| データ量が偏りにくい | 大口顧客をさらに分散できる設計 | 1つの値に大半のデータが集まる |
| 将来の拡張に耐える | 階層型や合成キーを検討済み | 現在の画面だけに最適化 |
Microsoftのパーティショニング解説では、パーティションキーは高カーディナリティで、RU消費とデータ保存を論理パーティションに均等に分散できるものが望ましいとされています。(Microsoft Learn)
大規模SaaSでは、単純な /tenantId だけでは特定テナントが肥大化する場合があります。このような場合、階層型パーティションキーを使うと、最大3階層までのキーを構成でき、データ分散をさらに最適化できます。(Microsoft Learn)
移行時に失敗しやすいポイント
今回のGAで作業は簡単になりましたが、失敗しやすいポイントは残っています。
新しいパーティションキーとidの組み合わせが重複する
Azure Cosmos DBでは、アイテムの一意性はパーティションキーとidの組み合わせで判断されます。Container copy jobsの既知の問題として、新しいパーティションキーとidの組み合わせが宛先コンテナー内で重複すると、挿入エラーになる可能性が示されています。(Microsoft Learn)
たとえば、旧キーが /department で、同じ id を部署ごとに使っていたとします。新キーを /employeeName に変えた結果、同じ従業員名と同じ id の組み合わせが複数できると、宛先で衝突します。
移行前に、次のような観点で重複チェックを行ってください。
-- 考え方の例：新パーティションキー候補とidの組み合わせが一意か確認する
newPartitionKeyValue + id実際の確認方法はデータ量や分析基盤によって異なりますが、Cosmos DBのクエリだけで無理に全件検証するより、必要に応じてAzure Data Explorer、Spark、Fabric、エクスポートデータなどで事前集計する方が安全です。
オンライン移行でも最後に短時間の停止が必要になる
オンラインモードは「完全無停止」を保証するものではありません。Microsoftの手順でも、オンラインコピーでは処理済みドキュメント数が総数に近づいた段階でソースへの書き込みを止め、Completeを選択して残りの変更を反映する流れが示されています。(Microsoft for Developers)
実務では、次のような短い切り替え手順を用意します。
| タイミング | 作業 |
|---|---|
| 切り替え直前 | 書き込みAPIをメンテナンスモードにする |
| コピー追いつき後 | portalでCompleteを実行する |
| 完了後 | アプリ設定を新コンテナーへ切り替える |
| 再開前 | 代表的な読み取り・書き込みを確認する |
| 再開後 | 429、5xx、RU、レイテンシを監視する |
「オンラインだから停止計画はいらない」と考えると、最後の整合性確認で慌てることになります。短時間でも、事前に関係者へ通知し、戻し手順を決めておくべきです。
RU不足で移行が長引く
コピー処理はスループットを消費します。ターゲット側のRUが低いとコピーが進まず、ソース側の通常処理にも影響が出る可能性があります。
本番移行では、次のように考えると現実的です。
| 状況 | 対応 |
|---|---|
| 日中もトラフィックが多い | 夜間・休日に実行する |
| コピー時間を短くしたい | 一時的にターゲットRUを上げる |
| Autoscaleを使っている | 上限RUとコストを事前に見積もる |
| 429が増えた | コピー速度、RU、実行時間帯を見直す |
移行中だけRUを上げ、完了後に適正値へ戻す運用も検討できます。ただし、コスト影響は事前に見積もっておきましょう。
TTLやインデックス、Unique Keyの差分を見落とす
Azure portalで新しいコンテナーを作成する場合、Microsoft LearnではパーティションキーとUnique Keyを除く構成が宛先に複製されると説明されています。(Microsoft Learn)
逆に言えば、Unique Keyは自動で同じになると決めつけない方が安全です。また、既存コンテナーを宛先に選ぶ場合は、インデックスポリシー、TTL、スループット、Unique Key、分析ストアなどの設定差分を必ず確認してください。
TTLについては、Container copy jobsのドキュメントで、宛先コンテナーのTTL設定は調整されず、ソースで期限切れになっていないドキュメントは宛先でカウントダウンが新たに始まると説明されています。(Microsoft Learn)
どのようなケースで使うべきか
この機能は、すべてのコンテナーで急いで使うものではありません。移行のリスクと得られる効果を比較して判断します。
使う価値が高いのは、次のようなケースです。
- 特定のパーティションキー値にアクセスが集中し、429や遅延が増えている
- 主要クエリがクロスパーティションになり、RUコストが高い
- 1テナント、1ユーザー、1カテゴリのデータが大きくなりすぎている
- 新機能追加により、検索条件やデータモデルが大きく変わった
- 手作業の移行コードを作るより、公式のコピー機能に寄せたい
逆に、次のような場合は急いで変更しない方がよいでしょう。
- 現在のRU、レイテンシ、データ分散に問題がない
- 新しいパーティションキー候補がまだ決まっていない
- アプリ側のクエリやSDK実装を把握できていない
- ロールバック手順を用意できない
- プレビュー機能や未検証の設計に依存しすぎている
パーティションキー変更は、性能改善の特効薬ではありません。クエリ設計、インデックス、データモデル、キャッシュ、読み取りパターンを一緒に見直して初めて効果が出ます。
本番展開前のチェックリスト
最後に、管理者・開発者が本番展開前に確認すべき項目をまとめます。
| チェック | 確認内容 |
|---|---|
| 対象サービス | Azure Cosmos DB for NoSQLであり、Azure SQLではない |
| 新キー設計 | 高カーディナリティ、安定値、主要クエリとの一致を確認した |
| 重複確認 | 新パーティションキーとidの組み合わせが衝突しない |
| データ量 | 4TB超や高RU環境など、サポート相談が必要な条件に該当しないか確認した |
| RU計画 | 移行中のRU増加、ターゲットRU、実行時間帯を決めた |
| モード選択 | オンライン／オフラインのどちらで行うか決めた |
| 書き込み停止 | オンラインでも最終Complete前の短時間停止を計画した |
| アプリ設定 | 接続先コンテナー名、環境変数、IaC、CI/CDを更新した |
| 検証 | 主要API、検索、バッチ、監視、アラートを新コンテナーで確認した |
| ロールバック | 旧コンテナー保持期間、戻し方、判断基準を決めた |
今回のGAにより、Azure Cosmos DB for NoSQLのパーティションキー変更は、以前より現実的な選択肢になりました。まずは本番コンテナーに対していきなり実行するのではなく、現在のホットパーティション、クロスパーティションクエリ、RU消費を確認し、新しいパーティションキー候補を検証環境で試すことから始めましょう。切り替え計画まで含めて準備できれば、性能改善と運用コスト削減の両方を狙える更新です。
コメント