Azure Data Factory（ADF）で Snowflake コネクタを V1 から V2 へ切り替えるタイミングは、多くの現場で「いつかはやらなければならない技術的負債の解消」です。一方で、本番環境のパイプラインを止めずに安全に移行し、問題があれば素早くロールバックできる手順を整理しておかないと、思わぬ障害につながります。この記事では、実際に遭遇しがちなエラーや落とし穴を整理しながら、Snowflake リンクドサービスを V1 から V2 へアップグレードするベストプラクティスとロールバック戦略を詳しく解説します。
Azure Data Factory と Snowflake コネクタ V1 / V2 の位置づけ
まずは前提として、ADF における Snowflake 連携の構造を整理します。
- リンクドサービス（Linked Service）：接続先（Snowflake）の接続情報・認証情報を定義する。
- データセット（Dataset）：Snowflake 上のテーブルやビュー、クエリ結果を ADF 側で表現したもの。
- パイプライン（Pipeline）：Copy、Lookup、Script などのアクティビティを組み合わせた処理フロー。
Snowflake のコネクタには V1 と V2 が存在し、V2 は最新の接続方式や認証方式に対応し、パフォーマンスや機能面が強化されています。そのため、中長期的には すべての Snowflake 接続を V2 に統一すること が推奨されます。
しかし、単純に「Upgrade Advisor でポチっと一括変換」するだけでは済まないのが実情です。特に以下のようなケースで問題が表面化しやすくなります。
- Lookup アクティビティや Script アクティビティで Snowflake を呼び出している。
- パイプラインの一部だけを対象にインクリメンタルにアップグレードしたい。
- 開発環境と本番環境で発行状態や削除済みリソースの扱いが異なる。
よく遭遇するエラー「Cannot read properties of undefined (reading ‘isV2’)」とは
質問にあるように、本番環境で 一部のパイプラインだけを選択して Upgrade Advisor を実行した際 に、次のエラーが発生するケースがあります。
TypeError: Cannot read properties of undefined (reading 'isV2')
このエラーは、Upgrade Advisor が内部で「リンクドサービスやデータセットが V2 かどうか」を判定しようとした際、想定しているオブジェクトが取得できず undefined になっている 状態で発生します。
エラーの主因：依存グラフが壊れている
実際の原因は、次のようなケースで発生しがちです。
- 既に削除したはずの V1 リンクドサービス／データセットがどこかのパイプラインからまだ参照されている。
- 本番環境に 未発行の変更 が残っており、ポータル画面と実際のメタデータの状態がズレている。
- 一部のパイプラインだけを選択したことで、Upgrade Advisor の内部で組み立てる依存関係グラフが不完全になっている。
ざっくりいうと、Upgrade Advisor が「このリンクドサービスは V2 かな？」と判断しようとした瞬間に、そのリンクドサービス自体がうまく解決できず、isV2 プロパティを読もうとして失敗しているイメージです。
よくあるパターンを表にすると以下のようになります。
| 発生パターン | 原因 | 症状 |
|---|---|---|
| 一部パイプラインのみ選択 | 依存するデータセットやリンクドサービスが対象外になり、依存グラフが欠落 | Upgrade Advisor 実行時に isV2 関連の TypeError |
| 削除済み V1 リンクドサービス | コード上はまだ参照が残っているが、ポータル上は見えない（Soft Delete / 未発行） | 一部パイプラインのみアップグレードするとエラー、本体が見つからない |
| 未発行の変更が多い | ポータル画面と実際の ARM メタデータの状態が異なる | 開発環境では成功するが、本番環境のみエラー |
質問に記載の通り、すべてのパイプラインを一括選択すればエラーが出ない というのは、Upgrade Advisor が依存関係を完全に把握できる状態になるためと考えるのが自然です。
推奨されるアップグレード方針：全体一括＋事前クリーンアップ
結論から言うと、以下の手順で進めるのが最も安全で、かつトラブルが少ない進め方です。
| 手順 | 内容 | ポイント |
|---|---|---|
| ① 事前クリーンアップ | 不要な V1 リンクドサービス／データセットを削除し、すべての変更を発行済みに揃える | 依存グラフをクリーンにしてから Upgrade Advisor を実行 |
| ② 全パイプライン一括選択 | Connector Upgrade Advisor で工場全体を対象に Snowflake V1 → V2 へ変換 | 中途半端なサブセット選択を避け、依存関係の欠落を防ぐ |
| ③ 手動確認 | Lookup / Script など自動置換されない箇所を手動で V2 データセット／リンクドサービスに張り替える | GUI または JSON の直接編集で丁寧に確認 |
| ④ 検証＆リリース | トリガーを一時停止し、スモークテスト → 段階的に本稼働へ移行 | 小さなデータから確認し、本番負荷での挙動も順次チェック |
この流れで進めることで、「一部だけ V2、残りは V1」という中途半端な状態を最短期間に抑えられ、エラー要因を減らすことができます。
事前クリーンアップの具体的なチェックリスト
事前クリーンアップの段階では、以下のポイントを重点的に確認します。
| チェック項目 | 確認方法 | 注意点 |
|---|---|---|
| 未使用 V1 リンクドサービスの削除 | 「参照している項目」を確認し、参照 0 のものを削除 | 実行中パイプラインがない時間帯に行う |
| 未使用 V1 データセットの削除 | データセット一覧から参照状況を確認 | 共有データセット（多くのパイプラインで使用）は要注意 |
| 未発行の変更の解消 | ADF ポータル上で「すべての変更を発行」 | Git 統合環境なら PR をマージしてから本番へデプロイ |
| 削除済みリソースの痕跡確認 | コードビューで古い V1 名称が残っていないか検索 | 特に JSON 内の linkedServiceName を検索 |
ここまでできていれば、Upgrade Advisor 実行時の「isV2」エラー発生率はかなり下がります。
Lookup / Script アクティビティが自動移行されない理由と対処
質問にもある通り、開発環境の Upgrade Advisor では Copy アクティビティなどは V2 に置き換わったものの、Lookup や Script アクティビティは自動では V2 に切り替わらないことがあります。これは、アクティビティ内の設定がより柔軟（＝パターンが多い）ため、安全に自動変換しづらい からです。
自動アップグレード対象外になりやすいアクティビティ
| アクティビティ種別 | 典型的な利用パターン | V2 対応時の手作業 |
|---|---|---|
| Lookup | Snowflake テーブルやクエリ結果を参照して変数に格納 | 使用データセットを V2 対応のものに変更 |
| Script | Snowflake 上で SQL スクリプトを実行 | リンクドサービスを V2 対応の Snowflake に変更 |
| Stored Procedure / Custom アクティビティ | Snowflake をバックエンドとして利用するカスタムロジック | 接続先設定を V2 に張り替え、動作検証 |
Lookup アクティビティを V2 に対応させる手順例
- まず、Snowflake V2 接続用のリンクドサービスを作成しておく。
- V2 用のデータセットを新規作成し、テーブル名やクエリを V1 データセットと揃える。
- 対象の Lookup アクティビティを開き、使用しているデータセットを V1 → V2 に変更。
- 必要に応じて、パラメータやスキーママッピングを再確認。
- デバッグ実行で想定通りの JSON / 行が取得できているかを確認。
ポイントは、V1 データセットをそのまま上書きするのではなく、V2 用に新規作成してから切り替える ことです。これにより、もし動作に問題があった場合も、すぐに V1 データセットに戻すことができます。
Script アクティビティを V2 に対応させる手順例
- Snowflake V2 用リンクドサービスを作成しておく（認証方式やロールの設定も確認）。
- Script アクティビティの設定画面を開き、リンクドサービスを V1 → V2 に変更。
- 接続先 DB、スキーマ、ロールなどが V2 でも正しく選択されているかを確認。
- パラメータ化された接続の場合、パラメータの既定値で V2 への接続情報が解決されるか確認。
- テスト用パラメータでデバッグ実行し、SQL が正常完了するか／戻り値に問題がないか確認。
JSON 直接編集による一括修正テクニック
Lookup や Script の数が多い場合、GUI から 1 つずつ張り替えるのはかなりの手間です。そこで、Git 統合を有効にしている場合は、リポジトリ上で JSON を検索・置換して一括修正する方法も有効です。
"linkedServiceName": "SnowflakeV1"を"linkedServiceName": "SnowflakeV2"に置換。- 必要に応じて、V1 専用のパラメータ名やプロパティ名を V2 用に変更。
- 置換後に JSON が壊れていないか、フォーマッタや linter で確認。
- 最終的には ADF 上でパイプラインを開き、GUI で正しく認識されているかを確認。
ただし、一括置換は破壊力も大きいので、必ず ブランチを切る／バックアップを取る など安全策をとったうえで行ってください。
インクリメンタルにアップグレードしたい場合の注意点
現実には、「いきなりすべてのパイプラインを V2 に変えるのは怖いので、まずは一部だけで試したい」というニーズもあります。その場合のポイントは、対象パイプラインの周辺にある依存関係を丸ごと含める ことです。
対象パイプライン周辺の依存関係チェック
インクリメンタルアップグレードを行う際は、少なくとも次の観点をチェックします。
- 対象パイプラインで利用している すべてのデータセットが発行済みかつ存在している か。
- 共有データセット（複数パイプラインで再利用されているもの）の扱い。
- トリガー単位で依存しているパイプラインの連鎖（親子関係）。
例えば、「PipelineA だけ V2 にする」つもりでも、PipelineA が共有データセット Ds_Snowflake_Common を利用していて、そのデータセットが PipelineB、C でも使われていた場合、実質的には B・C も影響を受ける ことになります。
パラメータ化されたリンクドサービスの落とし穴
リンクドサービスをパラメータ化している場合、Upgrade Advisor や GUI 上の検証では「既定値」を使って解決されます。そのため、
- 既定値では V2 接続先に見えるが、実際の本番トリガーでは別の値が入り、V1 接続を想定している。
- 既定値を V2 用に変えた結果、古いトリガーからの実行で想定外の接続先になってしまう。
といった問題が起こる可能性があります。対策としては、
- パラメータに「バージョン」情報を持たせ、明示的に
version = "V2"などとする。 - V1 用と V2 用のリンクドサービスを分け、トリガー単位でどちらを使うか明確にする。
といった運用ルールを決めておくと、後から見ても分かりやすく、トラブル時の切り戻しもしやすくなります。
安全なロールバック戦略：V2 → V1 はどうする？
次に、「もし V2 への移行で問題が出たらどう戻すか」という観点です。まず押さえておくべきなのは、
ADF の UI には Snowflake V2 → V1 へ自動的にダウングレードする機能はない
という事実です。一度 V2 に変えたリンクドサービスやデータセットを、ボタン 1 つで V1 に戻すことはできません。したがって、事前にスナップショットを確保しておき、問題があればその状態をまるごと復元する という考え方が重要になります。
ARM テンプレート／Git によるスナップショットの取り方
代表的なロールバック戦略は以下の 2 つです。
| 方式 | 概要 | メリット | デメリット |
|---|---|---|---|
| ARM テンプレートエクスポート | アップグレード前の ADF リソースを ARM テンプレートとしてエクスポート | ポータルから簡単にエクスポートでき、別環境への復元も容易 | エクスポートのタイミングを間違えると最新状態を取り逃がす |
| Git リポジトリ | Git 統合を有効化し、アップグレード前の状態をタグやブランチで固定 | 差分が見える／レビューできる／再現性が高い | Git 運用フローの整備が必要 |
現場での実践的な手順は以下のようになります。
- V1 から V2 へのアップグレードを実施する直前に、ARM テンプレートをエクスポートする、または Git リポジトリにコミットする。
- コミットやエクスポートに「pre-snowflake-v2-migration」など分かりやすいタグ／コメントを付ける。
- Upgrade Advisor 実行後、テストを行い、問題があればそのテンプレートやコミットから再デプロイする。
ADF インスタンスのクローンによる保険
より強固な安全策として、V1 のままの状態を保った ADF インスタンスを別環境にクローンしておく方法もあります。
- 例：
adf-prod（本番）とは別にadf-prod-backupを作成し、V1 状態をデプロイしておく。 - アップグレード後も一定期間は
adf-prod-backupをそのまま残し、緊急時の参照元として利用。 - JSON やスクリプトの「動いていた時点の姿」を、いつでも確認できるようにしておく。
この方法はコストは多少かかりますが、
- 「本番でだけ再現する不具合」を調査するときの比較対象になる。
- V1 時代の設定や SQL スクリプトを後から確認できる。
といった利点があり、重要度の高いシステムでは検討に値します。
ロールバック実行手順のサンプル
実際にトラブルが起きた場合の、ロールバックの流れの一例です。
- 該当の ADF インスタンスで すべてのトリガーを一時停止 する。
- 現在走っているパイプラインが完了するのを待つ、またはキャンセルする。
- アップグレード前に取得した ARM テンプレートまたは Git のコミットから、ADF リソースをV1 時点の状態で再デプロイする。
- テスト用パイプラインを手動実行し、V1 時代と同じ結果が得られるかを確認。
- 問題なければトリガーを再開し、運用を再開する。
ポイントは、ロールバックも「手順書」として事前に用意し、テストしておく ことです。いざというときに初めてやると、想像以上に時間がかかります。
トラブルシューティング：よくある問題と確認ポイント
Snowflake V2 への移行時によくあるトラブルを、原因・確認ポイント・対処の観点で整理します。
| 症状 | 主な原因 | 確認ポイント | 対処のヒント |
|---|---|---|---|
Upgrade Advisor で isV2 エラー | 依存グラフの欠落・削除済み V1 への参照 | 未使用 V1 リンクドサービス／データセットの有無、未発行変更の有無 | 事前クリーンアップ＋全体一括選択で再実行 |
| Lookup が突然失敗する | データセットを V2 に変更したがパラメータやスキーマの整合性が崩れた | 入力・出力スキーマ、SQL クエリ、パラメータのバインド | V1 の設定と V2 の設定を見比べながら差分を 1 つずつ潰す |
| Script アクティビティで接続エラー | V2 リンクドサービスのロールやネットワーク設定の違い | アカウント / ロール / ウェアハウス / ネットワークポリシー | 同じ認証情報で別ツールから Snowflake に接続して確認 |
| 本番だけ SQL の挙動が変わる | パラメータ化された接続／データベース名が V1 と V2 で異なる | トリガーから渡されるパラメータ、接続先 DB・スキーマ | 本番パラメータでデバッグ実行し、ログを詳細に確認 |
ステージング環境と自動テストの活用
本番環境でのトラブルを最小限に抑えるには、本番とほぼ同じ構成のステージング環境 を用意し、そこで Snowflake V2 への移行リハーサルを行うのが理想的です。
ステージング環境での検証シナリオ例
- 本番の ADF を ARM テンプレート経由でステージングにデプロイ。
- Snowflake 側のデータセットも、本番の一部データをマスキング／サンプリングしてコピー。
- ステージングで Upgrade Advisor を本番と同じ手順・同じ対象で実行。
- 全パイプラインのスモークテスト（10 件程度のデータ）と、代表的な大量データのパイプラインの負荷テストを実施。
ここで問題が出れば、ステージング環境で手当てをしてから本番に反映すれば良いので、本番でのトラブルは格段に減ります。
自動テストのアイデア
Snowflake V2 への移行にあわせて、パイプラインの整合性チェックを自動化してしまうのも有効です。例えば：
- Azure Databricks や Azure Functions から、特定テーブルのレコード件数やハッシュ値 を検証するスクリプトを用意。
- パイプライン完了後に、同じテーブルに対して V1 時代と V2 時代の結果を比較。
- 差分が一定閾値を超えた場合はアラートを送信し、ロールバック検討のトリガーにする。
このように、移行を機に「監視・テストも強化してしまう」発想で動くと、長期的な運用コストも下がります。
Git 統合と運用プロセスの整備
Snowflake コネクタの V1 → V2 移行は、単なる設定変更ではなく、データ基盤全体のライフサイクル管理を見直す良いきっかけ になります。特に次のような運用プロセスを整えておくと、今後のバージョンアップや改修もスムーズです。
- ADF を Git 統合し、すべての変更を PR 経由でレビュー。
- リンクドサービス・データセット・パイプラインごとに命名規約を整備（例：
ls-snowflake-v2-prodなど）。 - 本番用ブランチとステージング用ブランチを明確に分け、ARM テンプレートによるデプロイを標準化。
- バージョンアップ時（例：Snowflake コネクタの将来のアップデート）に再利用できるよう、手順書を wiki 等に蓄積。
これらを整備しておけば、今回の V1 → V2 の経験を、そのまま将来のメンテナンスや他システムへの横展開に活かせます。
まとめ：正しい手順とロールバック戦略が安心感を生む
ここまで、Azure Data Factory で Snowflake リンクドサービスを V1 から V2 へアップグレードする際の課題と解決策を、実務の目線で整理してきました。
- 「TypeError: Cannot read properties of undefined (reading ‘isV2’)」エラーの原因 は、多くの場合、未発行や削除済み V1 リソースへの参照により依存グラフが壊れていること。
- アップグレードは、事前クリーンアップ → 全パイプライン一括選択 → 手動確認 → 検証＆リリース の流れで進めるのが安全。
- Lookup / Script など自動移行されない箇所は、V2 用データセット・リンクドサービスを用意して丁寧に張り替える。
- UI からの V2 → V1 ダウングレードはできないため、ARM テンプレートや Git によるスナップショット を前提にロールバック戦略を組み立てる。
- ステージング環境で本番相当のテストを行い、自動テストや監視もあわせて整備すると、移行後の運用が格段に安定する。
これらを押さえておけば、「本番で Upgrade Advisor を実行するのが怖い」という状況から、「きちんと手順とバックアップを用意したうえで、安心して移行できる」状態へと一歩進めるはずです。Snowflake コネクタ V2 への移行をきっかけに、ADF 全体の設計や運用プロセスも一段アップデートしていきましょう。
コメント