外部 DAG の v4.2 から v5.0 への移行

このガイドでは、外部有向非巡回グラフ（DAG）の出力テーブルを Cortex Data Foundation v5.0 アーキテクチャ内の新しい場所に移動するために必要な手順について説明します。たとえば、天気やトレンドなどです。このガイドは、以前の Cortex Framework Data Foundation バージョン（4.2 ～ 5.0）で外部 DAG を実装し、アップグレードするユーザーを対象としています。外部 DAG を使用していない場合や、SAP をデプロイしていない場合は、このガイドは適用されません。

コンテキスト

4.2 より前のバージョンの Cortex Framework Data Foundation では、_GEN_EXT フラグを使用して外部データソースのデプロイを管理していました。一部のソースは、特定のワークロード（SAP の通貨換算など）に関連付けられていました。ただし、バージョン 5.0 では、このフラグは削除されました。複数のワークロードに対応できる DAG を管理するための新しいモジュールが追加されました。このガイドでは、この新しい構造で動作するように既存のデータパイプラインを調整する手順について説明します。

ワークロード間で再利用可能な DAG

Cortex Framework Data Foundation v5.0 では、K9 という新しいコンポーネントが導入されました。このコンポーネントは、さまざまなデータソース間で共有される再利用可能なデータ要素の取り込み、処理、モデリングを行います。レポートビューは、K9_PROCESSING データセットを参照してこれらの再利用可能なコンポーネントにアクセスするようになり、データアクセスが効率化され、冗長性が軽減されます。次の外部データソースは、K9 の一部として K9_PROCESSING データセットにデプロイされるようになりました。

date_dimension
holiday_calendar
trends
weather

SAP 依存の DAG

次の SAP 依存の DAG は、引き続き generate_external_dags.sh スクリプトによってトリガーされますが、レポートのビルドステップで実行されるようになり、CDC（変更データキャプチャ）ステージではなく、SAP レポートデータセットに書き込むようになりました。

currency_conversion
inventory_snapshots
prod_hierarchy_texts

移行ガイド

このガイドでは、Cortex Framework Data Foundation をバージョン 5.0 にアップグレードする手順について説明します。

Cortex Framework Data Foundation 5.0 をデプロイする

まず、次のガイドラインに沿って、Cortex Framework Data Foundation の最新バージョン（v5.0）をプロジェクトにデプロイします。

デプロイ中に変更されないため、以前の開発またはステージングデプロイの既存の RAW データセットと CDC データセットを、このデプロイの RAW データセットと CDC データセットとして使用します。
config/config.json で testData と SAP.deployCDC の両方を False に設定します。
テスト用に、既存の v4.2 環境とは別の新しい SAP Reporting プロジェクトを作成します。これにより、現在のオペレーションに影響を与えることなく、アップグレードプロセスを安全に評価できます。
省略可。以前の Cortex Framework Data Foundation バージョンで Airflow DAG が実行されている場合は、移行に進む前に一時停止します。これは、Airflow UI で行うことができます。詳細な手順については、 Composer から Airflow UI を開くおよび DAG を一時停止するをご覧ください。

これらの手順に沿って、Cortex Framework Data Foundation バージョン 5.0 に安全に移行し、新機能と機能を検証できます。

既存のテーブルを移行する

既存のテーブルを新しい場所に移行するには、jinja-cli を使用して、提供されている移行スクリプトテンプレートをフォーマットして移行を完了します。

次のコマンドで jinja-cli をインストールします。
```
pip install jinja-cli
```
既存のバージョン 4.2 と新しいバージョン 5.0 のデプロイから、次のパラメータを特定します。
<td"> 名前 <td"> 説明 </td"></td"><td"> project_id_src <td"> Source Google Cloud Project: バージョン 4.2 デプロイの既存の SAP CDC データセットが配置されているプロジェクト。K9_PROCESSING データセットもこのプロジェクトに作成されます。 </td"></td"><td"> project_id_tgt <td"> ターゲット Google Cloud 新しいバージョン 5.0 デプロイから新しくデプロイされた SAP Reporting データセットが配置されている場所。これは、ソースプロジェクトとは異なる場合があります。 </td"></td"><td"> dataset_cdc_processed <td"> CDC BigQuery データセット: CDC 処理済みデータが最新の利用可能なレコードに格納される BigQuery データセット。これは、ソースデータセットと同じ場合があります。 </td"></td"><td"> dataset_reporting_tgt <td"> Target BigQuery レポートデータセット: SAP 用 Data Foundation の事前定義されたデータモデルがデプロイされる BigQuery データセット。 </td"></td"><td"> k9_datasets_processing <td"> K9 BigQuery データセット: K9（拡張データソース）がデプロイされる BigQuery データセット。 </td"></td">

必要な入力データを含む JSON ファイルを作成します。移行しない DAG は、migrate_list セクションから削除してください。

{
  "project_id_src": "your-source-project",
  "project_id_tgt": "your-target-project",
  "dataset_cdc_processed": "your-cdc-processed-dataset",
  "dataset_reporting_tgt": "your-reporting-target-dataset-OR-SAP_REPORTING",
  "k9_datasets_processing": "your-k9-processing-dataset-OR-K9_REPORTING",
  "migrate_list":
    [
        "holiday_calendar",
        "trends",
        "weather",
        "currency_conversion",
        "inventory_snapshots",
        "prod_hierarchy_texts"
    ]
}
EOF

たとえば、weather と trends を削除する場合、スクリプトは次のようになります。

{
  "project_id_src": "kittycorn-demo",
  "project_id_tgt": "kittycorn-demo",
  "dataset_cdc_processed": "CDC_PROCESSED",
  "dataset_reporting_tgt": "SAP_REPORTING",
  "k9_datasets_processing": "K9_PROCESSING",
  "migrate_list":
    [
        "holiday_calendar",
        "currency_conversion",
        "inventory_snapshots",
        "prod_hierarchy_texts"
    ]
    }

次のコマンドで出力フォルダを作成します。
```
  mkdir output
```
次のコマンドで、解析された移行スクリプトを生成します（このコマンドは、リポジトリのルートにいることを前提としています）。
```
  jinja -d data.json -o output/migrate_external_dags.sql docs/external_dag_migration/scripts/migrate_external_dags.sql
```
出力 SQL ファイルを調べて、BigQuery で実行し、テーブルを新しい場所に移行します。

Airflow DAG を更新して一時停止を解除する

Airflow バケット内の現在の DAG ファイルをバックアップします。次に、Cortex Framework Data Foundation バージョン 5.0 デプロイから新しく生成されたファイルに置き換えます。詳細な手順については、次のドキュメントをご覧ください。

検証とクリーンアップ

これで移行は完了です。新しい v5.0 レポートデプロイのすべてのレポートビューが正しく機能していることを検証できます。すべてが正しく動作する場合は、もう一度プロセスを実行します。今回は、v5.0 デプロイを本番環境のレポートセットにターゲット設定します。その後、次のスクリプトを使用してすべてのテーブルを削除できます。

    jinja -d data.json -o output/delete_old_dag_tables.sql docs/external_dag_migration/scripts/delete_old_dag_tables.sql