Azure SQL と Azure Cosmos DB for NoSQL を Azure Data Factory や Azure Synapse Analytics で連携している場合、今回まず確認すべきことは「既存パイプラインがすぐ壊れる変更ではないか」ではなく、「ADF/Synapse から Microsoft Fabric Data Factory への導線が追加され、将来の移行判断に関係する情報が増えた」という点です。公式ドキュメント自体は、Azure Cosmos DB for NoSQL とのコピー、変換、Lookup、認証、書き込み動作、RU 消費、Change Feed 利用時の注意点を整理した内容であり、Azure SQL Database や SQL Server から Cosmos DB へデータを移す設計にも関係します。(Microsoft Learn)
特に Azure SQL のテーブルデータを Cosmos DB for NoSQL に投入している環境では、単なるコネクタ設定の確認だけでなく、JSON への変換方針、id の扱い、Upsert の挙動、パーティションキー、RU、スキーママッピングまで見直すことが重要です。
Azure SQL の更新ではなく、ADF/Synapse の Cosmos DB for NoSQL コネクタ更新として見る
今回のトピック名には Azure SQL が含まれていますが、公式情報の主対象は Azure SQL エンジンそのものではありません。対象は、Azure Data Factory と Azure Synapse Analytics で Azure Cosmos DB for NoSQL にデータをコピーし、Mapping Data Flow で変換するためのコネクタです。公式ドキュメントでも、Copy Activity で Azure Cosmos DB for NoSQL との入出力を行い、Data Flow で Cosmos DB 上のデータを変換する方法を説明しています。(Microsoft Learn)
Azure SQL 管理者に関係するのは、次のような構成です。
| 構成例 | 関係するポイント |
|---|---|
| Azure SQL Database から Cosmos DB for NoSQL へデータを同期 | リレーショナル表を JSON ドキュメントへどうマッピングするか |
| SQL Server から ADF 経由で Cosmos DB へ移行 | 初回フルコピー、差分同期、Upsert、RU 見積もり |
| Cosmos DB のデータを Azure SQL や分析基盤へ戻す | スキーマ推論ではなく明示マッピングが必要 |
| ADF/Synapse から Fabric Data Factory へ移行検討 | コネクタ、認証、データフロー、接続管理の差分確認 |
したがって、この記事では「Azure SQL の新機能」としてではなく、Azure SQL 周辺のデータ連携に影響する ADF/Synapse の Cosmos DB for NoSQL コネクタ更新として整理します。
2026年6月下旬の更新ポイント
公式ドキュメントの GitHub 履歴では、2026年6月25日に ADF コネクタ記事群へ Microsoft Fabric Data Factory の対応コネクタへのリンクを追加するコミットが確認できます。該当コミットでは 62 ファイルに対して Fabric Data Factory への案内が追加され、Azure Cosmos DB for NoSQL コネクタの記事にも「このコネクタは Data Factory in Microsoft Fabric でも利用できる」という注記と Fabric 側コネクタ文書へのリンクが追加されています。(GitHub)
一方で、Microsoft Learn の該当ページに表示される Last updated は 2025年7月25日のままです。つまり、2026年6月29日前後の更新として扱う場合でも、機能仕様が大きく変わったというより、Fabric Data Factory への関連情報が追加されたドキュメント更新と見るのが安全です。(Microsoft Learn)
今回の実務上の要点は、次の3つです。
| 確認項目 | 内容 | 管理者の対応 |
|---|---|---|
| 既存 ADF/Synapse パイプライン | 直ちに変更が必要な破壊的変更は読み取れない | 既存ジョブの動作確認と設定棚卸しを実施 |
| Fabric Data Factory への導線 | ADF コネクタ記事から Fabric 側の対応ドキュメントへ移動しやすくなった | 中長期の移行候補として Fabric 側の差分を確認 |
| Azure SQL 連携 | SQL の表データを Cosmos DB の JSON に移す設計で影響が出やすい | スキーマ、id、Upsert、RU、パーティションキーを重点確認 |
何ができるコネクタなのか
Azure Cosmos DB for NoSQL コネクタは、Copy Activity、Mapping Data Flow、Lookup Activity に対応しています。Copy Activity では Azure Integration Runtime と Self-hosted Integration Runtime を利用でき、Mapping Data Flow は Azure Integration Runtime 側で利用する構成です。(Microsoft Learn)
Copy Activity では、主に次の処理ができます。
| 処理 | できること |
|---|---|
| Cosmos DB から読み取り | クエリ、ページサイズ、優先リージョン、日時検出などを指定して取得 |
| Cosmos DB へ書き込み | Insert または Upsert で書き込み |
| JSON のそのままコピー | Cosmos DB コレクション間、またはファイルストアとの間で JSON ドキュメントを保持 |
| 表形式データとの変換 | SQL Database や CSV などの表形式データと Cosmos DB の JSON をマッピング |
| Lookup | パイプライン内で Cosmos DB のデータを参照 |
注意したいのは、このコネクタが Azure Cosmos DB for NoSQL 専用である点です。Azure Cosmos DB for MongoDB など別 API を利用している場合は、別のコネクタを参照する必要があります。(Microsoft Learn)
Azure SQL 連携で特に重要な設計ポイント
Azure SQL Database や SQL Server のデータを Cosmos DB for NoSQL に移す場合、最も失敗しやすいのは「テーブルをそのままコピーすればよい」と考えてしまうことです。Cosmos DB は NoSQL のドキュメントデータベースであり、リレーショナルデータをそのまま正規化構造のまま移すと、アプリ側のクエリ効率や RU 消費が悪化することがあります。
公式ドキュメントでも、リレーショナルデータベースから Cosmos DB へ移行する場合、Copy Activity で表形式データを JSON ドキュメントへマッピングできる一方、NoSQL のユースケースに合わせてデータモデルを再設計し、関連する子要素を1つの JSON ドキュメントに埋め込むような非正規化を検討するケースがあると説明されています。(Microsoft Learn)
Azure SQL から Cosmos DB へ移す前に決めること
| 決めること | 判断基準 | 失敗しやすい例 |
|---|---|---|
| 1ドキュメントの単位 | アプリが1回の読み取りで必要とするまとまり | SQL の1行を機械的に1ドキュメント化し、読み取りが複数回に分かれる |
id の作り方 | Upsert や差分同期で同じレコードを識別できるか | id を指定せず、自動生成されて重複登録される |
| パーティションキー | 高頻度アクセスの条件、データ分散、更新単位 | 低カーディナリティの列を使い、特定パーティションに負荷が偏る |
| スキーママッピング | JSON の入れ子、配列、null の扱い | 最初の行だけでスキーマ推論させ、一部列が欠落する |
| 書き込み方式 | 初回投入か、再実行・差分更新があるか | 再実行が必要なのに Insert のまま運用する |
| RU とバッチサイズ | 1ドキュメントのサイズ、書き込み量、スループット | 大きな JSON を大きなバッチで投入し、リクエストサイズエラーになる |
特に Upsert を使う場合は、ドキュメントに安定した id が必要です。公式ドキュメントでは、Upsert は同じ ID のドキュメントがあれば置換し、なければ挿入する動作であり、id が指定されていないとサービス側で ID が自動生成されるため、期待通りの Upsert にならない可能性があると説明されています。(Microsoft Learn)
設定変更で確認すべき項目
既存の ADF/Synapse パイプラインを管理している場合、今回の更新を機に次の設定を棚卸ししておくと、将来の障害や移行時の手戻りを減らせます。
Linked Service の認証方式
Azure Cosmos DB for NoSQL コネクタでは、キー認証、サービスプリンシパル認証、システム割り当てマネージド ID、ユーザー割り当てマネージド ID が説明されています。キー認証では接続文字列にアカウントキーを直接含めるだけでなく、Azure Key Vault に格納した accountKey を参照する構成も示されています。(Microsoft Learn)
実務では、次の順で見直すとよいでしょう。
| 認証方式 | 向いているケース | 注意点 |
|---|---|---|
| キー認証 | 簡単な検証、既存構成の維持 | キーを接続文字列に直書きしない。Key Vault 参照を優先 |
| サービスプリンシパル | アプリ単位で権限管理したい | Data Flow ではサポート対象外とされているため、Copy Activity と Data Flow の混在に注意 |
| システム割り当てマネージド ID | ADF/Synapse リソース単位で権限を持たせたい | Data Flow では JSON の advanced properties を使う前提がある |
| ユーザー割り当てマネージド ID | 複数リソースで同じ ID を使いたい | credential 参照や権限付与の整理が必要 |
セキュリティ面では、キーのローテーション、Key Vault のアクセス権、Cosmos DB 側のロール割り当て、ADF/Synapse のマネージド ID の棚卸しをセットで確認してください。
Dataset とレガシー型
データセットでは CosmosDbSqlApiCollection が説明されており、古い DocumentDbCollection 型は Copy Activity と Lookup Activity では後方互換としてサポートされる一方、Data Flow ではサポートされないとされています。(Microsoft Learn)
既存環境で古い JSON 定義を使っている場合、すぐに動かなくなるとは限りません。ただし、将来の保守性を考えると、新規作成や大規模改修のタイミングで新しいモデルへ寄せるのが安全です。
Source のクエリとマッピング
Cosmos DB から Azure SQL やファイルへ出力する場合、Copy Activity の source では query、preferredRegions、pageSize、detectDatetime などを設定できます。(Microsoft Learn)
特に重要なのはマッピングです。公式ドキュメントでは、JSON ドキュメントをそのままエクスポートする場合を除き、Copy Activity で明示的にマッピングを指定するのがベストプラクティスとされています。マッピングを指定しない場合、最初の行を使ってスキーマが推論されるため、最初の行に存在しない列が結果から欠落する可能性があります。(Microsoft Learn)
この挙動は、Azure SQL 側へ戻す処理で特に問題になります。Cosmos DB のドキュメントは項目の有無がレコードごとに異なるため、最初のドキュメントだけを基準にすると、後続ドキュメントにしか存在しない項目が取り込まれません。
Sink の Upsert、バッチ、RU
Cosmos DB へ書き込む場合、sink では writeBehavior、writeBatchSize、disableMetricsCollection、maxConcurrentConnections などが関係します。writeBehavior は Insert と Upsert を選択でき、既存 ID がある場合に置換したい差分同期では Upsert が候補になります。(Microsoft Learn)
また、Azure Cosmos DB には1リクエストあたりのサイズ制限があり、公式ドキュメントでは「Request Size = Single Document Size × Write Batch Size」という考え方で、リクエストサイズが大きすぎるエラーが出た場合は writeBatchSize を下げるよう説明されています。(Microsoft Learn)
| 症状 | よくある原因 | 対応 |
|---|---|---|
| Upsert したのに重複する | id が未指定、または毎回変わる | Azure SQL の主キーなどから安定した id を生成 |
| 書き込みが遅い | RU 不足、バッチサイズが小さすぎる、リージョン距離 | RU、writeBatchSize、IR の配置を見直す |
| Request size is too large | 1ドキュメントが大きい、バッチが大きい | writeBatchSize を下げる、ドキュメント設計を分割 |
| 一部列が欠落する | スキーマ推論に依存 | 明示マッピングを設定 |
| Cosmos DB 側で RU が急増 | 並列度やバッチが過大 | maxConcurrentConnections や RU 予算を制御 |
Mapping Data Flow と Change Feed の注意点
Mapping Data Flow では、Cosmos DB のコレクションをソースまたはシンクとして利用できます。ただし、公式ドキュメントでは Azure Cosmos DB serverless は Mapping Data Flow でサポートされないとされています。(Microsoft Learn)
Data Flow の Source transformation では、システム列の取り込み、ページサイズ、スループット、優先リージョン、Change Feed の利用などを設定できます。Change Feed を有効にすると、Cosmos DB の変更履歴を読み取り、変換して別のデータセットへロードできます。Azure Functions で Change Feed を読んで独自変換を書く代わりに、ADF の視覚的な Data Flow で処理できる点が利点です。(Microsoft Learn)
ただし、Change Feed 利用時はチェックポイントの扱いに注意が必要です。公式ドキュメントでは、パイプライン名やアクティビティ名を変更するとチェックポイントがリセットされ、次回実行で最初から読み直す、または変更分の取得位置が変わる可能性があると説明されています。(Microsoft Learn)
運用では、次のルールを決めておくと安全です。
| 運用ルール | 理由 |
|---|---|
| パイプライン名とアクティビティ名を不用意に変えない | Change Feed のチェックポイントがリセットされる可能性がある |
| デバッグ後に本番初回実行の取得範囲を確認する | デバッグ時の挙動と公開後の初回実行で取得開始点を誤解しやすい |
| 初回フルロードと差分同期を分けて設計する | 再実行時に重複・欠落を防ぎやすい |
Upsert 用の id を固定する | 差分反映の再実行に強くなる |
Microsoft Fabric Data Factory への移行期限はあるのか
今回の対象ドキュメントと 2026年6月下旬の差分からは、ADF/Synapse パイプラインに対する強制移行期限や即時の設定変更義務は読み取れません。実質的な更新は、ADF コネクタ記事から Fabric Data Factory 側の対応コネクタ文書へ案内するリンク追加です。(GitHub)
ただし、Microsoft Fabric Data Factory は Azure Data Factory の後継的な位置づけとして説明されており、既存 ADF ワークロードを Fabric へ移行するための計画ガイドや組み込みアップグレード体験も用意されています。Fabric の移行計画ドキュメントでは、ADF と Fabric の違いとして、Linked Service と Connection、Data Flow と Dataflow Gen2、Managed Identity と Workspace Identity、トリガーやスケジュール管理などの差分が挙げられています。(Microsoft Learn)
そのため、現時点で取るべき対応は「すぐ移行」ではなく、「移行できるパイプラインと、再設計が必要なパイプラインを分ける」ことです。
Fabric 側で確認すべき差分
Fabric Data Factory 側にも Azure Cosmos DB for NoSQL コネクタのドキュメントが用意されています。Fabric のコネクタ概要では、Pipeline の Copy Activity、Lookup Activity、Copy job などの対応が説明されています。(Microsoft Learn)
ただし、ADF と Fabric は完全に同じではありません。コネクタ比較ドキュメントでは、Azure Cosmos DB for NoSQL について、ADF は Key、Service principal、System-assigned managed identity、User-assigned managed identity を扱う一方、Fabric 側では Account key、Workspace identity、Organizational account などの観点で整理されています。(Microsoft Learn)
Azure SQL 連携まで含めて Fabric 移行を検討する場合は、Cosmos DB 側だけでなく Azure SQL Database コネクタの差分も確認が必要です。Fabric のコネクタ比較では、Azure SQL Database について ADF 側で対応していた一部の接続プロパティが Fabric 側ではサポートされない項目として整理されています。(Microsoft Learn)
移行前チェックでは、少なくとも次を確認してください。
| 確認対象 | ADF/Synapse 側 | Fabric 側での確認観点 |
|---|---|---|
| 接続管理 | Linked Service | Connection へ置き換わる |
| データセット | 再利用可能な Dataset | アクティビティ内に設定が入るケースがある |
| 認証 | Key、Service principal、Managed Identity | Workspace identity や Organizational account を含めて再確認 |
| Azure SQL 接続 | Always Encrypted や追加接続文字列プロパティを使う場合あり | Fabric 側で同じ設定が使えるか確認 |
| データ変換 | Mapping Data Flow | Dataflow Gen2 など別エンジンとの差分を確認 |
| スケジュール | ADF トリガー | Fabric ではスケジュール管理の考え方が異なる |
管理者が今すぐ確認すべきチェックリスト
今回の更新を受けて、Azure SQL や Cosmos DB の管理者、データ基盤担当者は次の順で確認すると効率的です。
| 優先度 | 確認内容 | 具体的な作業 |
|---|---|---|
| 高 | Cosmos DB for NoSQL コネクタの利用有無 | ADF/Synapse の Linked Service、Dataset、Pipeline JSON を検索 |
| 高 | DocumentDbCollection など古い型の有無 | Data Flow 利用予定がある場合は新しいモデルへ寄せる |
| 高 | Upsert の id 設計 | Azure SQL の主キー、業務キー、複合キーから安定 ID を作る |
| 高 | 明示マッピングの有無 | スキーマ推論に依存していないか確認 |
| 高 | 認証情報の保管場所 | Key Vault 参照、マネージド ID、ロール割り当てを確認 |
| 中 | RU とバッチサイズ | writeBatchSize、並列度、Cosmos DB のスループットを確認 |
| 中 | Change Feed のチェックポイント | パイプライン名・アクティビティ名の変更ルールを決める |
| 中 | Fabric 移行候補 | パイプラインを「そのまま移行」「要修正」「再設計」に分類 |
| 低 | ドキュメントリンク | 運用手順書に Fabric 側コネクタへの参照を追加 |
特に、Azure SQL から Cosmos DB へ定期同期している場合は、id、Upsert、明示マッピングの3点を先に確認してください。この3つが曖昧なまま本番運用すると、再実行時の重複、列欠落、意図しない上書きが起きやすくなります。
実務での見直し例
例：Azure SQL の顧客マスタを Cosmos DB に同期する
Azure SQL の Customers テーブルを Cosmos DB にコピーする場合、単純に列をフラットな JSON にするだけではなく、アプリが顧客単位で参照する情報を1ドキュメントにまとめるかを検討します。
たとえば、顧客基本情報、住所、連絡先、契約ステータスを頻繁に一緒に読むなら、Cosmos DB 側では次のような1ドキュメントにまとめる設計が候補になります。
{
"id": "customer-10001",
"customerId": 10001,
"name": "Example Customer",
"status": "Active",
"address": {
"prefecture": "Tokyo",
"city": "Chiyoda"
},
"contacts": [
{
"type": "email",
"value": "[email protected]"
}
]
}この場合、ADF/Synapse 側では次を明確にします。
| 項目 | 設定例 |
|---|---|
id | customer- + Azure SQL の主キー |
| 書き込み方式 | 初回投入は Insert、定期同期は Upsert |
| マッピング | SQL 列から JSON の入れ子構造へ明示マッピング |
| パーティションキー | アクセスパターンに応じて /customerId やテナント ID などを検討 |
| RU | 初回投入時だけ一時的にスループットを上げるか検討 |
重要なのは、ADF の Copy Activity はデータ移動を助けるものであり、Cosmos DB のデータモデル設計を自動的に最適化してくれるわけではないという点です。Azure SQL の正規化テーブルをそのまま移す前に、アプリの読み取り単位を基準に JSON 構造を決めてください。
まとめ：今回の更新で取るべき次の行動
今回の「Copy and transform data in Azure Cosmos DB for NoSQL – Azure Data Factory & Azure Synapse」の更新ポイントは、既存の ADF/Synapse パイプラインに対する破壊的変更というより、Fabric Data Factory への案内が追加され、将来の移行検討に使うべき情報が増えた点にあります。Microsoft Learn の対象ページ自体は Cosmos DB for NoSQL コネクタの設定、認証、Copy Activity、Mapping Data Flow、Upsert、RU、Change Feed などを整理したドキュメントです。
Azure SQL 管理者が今すぐ行うべきことは、既存パイプラインの棚卸しです。Azure SQL から Cosmos DB へデータを送っている処理があるなら、id、Upsert、明示マッピング、RU、バッチサイズ、認証情報の保管場所を確認してください。あわせて、Fabric Data Factory へ移行する可能性がある環境では、ADF と Fabric のコネクタ差分、認証差分、データフロー差分を事前に整理しておくと、将来の移行判断がしやすくなります。
コメント