이 가이드에서는 외부 유향 그래프 (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를 설치합니다.
pipinstalljinja-cli
기존 버전 4.2 및 새 버전 5.0 배포에서 다음 매개변수를 식별합니다.
이름
설명
project_id_src
소스 Google Cloud 프로젝트: 버전 4.2 배포의 기존 SAP CDC 데이터 세트가 있는 프로젝트입니다. K9_PROCESSING 데이터 세트도 이 프로젝트에서 생성됩니다.
project_id_tgt
새 버전 5.0 배포에서 새로 배포된 SAP 보고 데이터 세트가 있는 Google Cloud 타겟 이는 소스 프로젝트와 다를 수 있습니다.
dataset_cdc_processed
CDC BigQuery 데이터 세트: CDC 처리 데이터가 사용 가능한 최신 레코드를 저장하는 BigQuery 데이터 세트입니다. 소스 데이터 세트와 동일할 수 있습니다.
dataset_reporting_tgt
대상 BigQuery 보고 데이터 세트: SAP 사전 정의 데이터 모델용 데이터 기반이 배포된 BigQuery 데이터 세트입니다.
k9_datasets_processing
K9 BigQuery 데이터 세트: K9 (증강 데이터 소스)가 배포된 BigQuery 데이터 세트입니다.
필요한 입력 데이터가 포함된 JSON 파일을 만듭니다. 이전하지 않을 DAG는 migrate_list 섹션에서 삭제해야 합니다.
이제 이전이 완료되었습니다. 이제 새 v5.0 보고 배포의 모든 보고 보기가 올바르게 작동하는지 확인할 수 있습니다. 모든 것이 제대로 작동하면 프로덕션 보고 세트에 v5.0 배포를 타겟팅하여 이 프로세스를 다시 진행합니다. 그런 다음 다음 스크립트를 사용하여 모든 테이블을 삭제해도 됩니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis guide details the migration process for external Directed Acyclic Graphs (DAGs) when upgrading from Google Cloud Cortex Framework versions 4.2 to 5.0, which involves relocating output tables to the new Cortex Data Foundation v5.0 architecture.\u003c/p\u003e\n"],["\u003cp\u003eCortex Framework Data Foundation v5.0 introduces a new K9 module for managing cross-workload reusable data elements like \u003ccode\u003edate_dimension\u003c/code\u003e, \u003ccode\u003eholiday_calendar\u003c/code\u003e, \u003ccode\u003etrends\u003c/code\u003e, and \u003ccode\u003eweather\u003c/code\u003e in the \u003ccode\u003eK9_PROCESSING\u003c/code\u003e dataset, which replaces the \u003ccode\u003e_GEN_EXT\u003c/code\u003e flag used in prior versions.\u003c/p\u003e\n"],["\u003cp\u003eSAP-dependent DAGs, including \u003ccode\u003ecurrency_conversion\u003c/code\u003e, \u003ccode\u003einventory_snapshots\u003c/code\u003e, and \u003ccode\u003eprod_hierarchy_texts\u003c/code\u003e, are now triggered during the reporting build step and write to the SAP reporting dataset instead of the CDC stage.\u003c/p\u003e\n"],["\u003cp\u003eThe migration process requires deploying Cortex Framework Data Foundation 5.0, using existing RAW and CDC datasets, and creating a new SAP Reporting project, before migrating existing tables using \u003ccode\u003ejinja-cli\u003c/code\u003e and an outputted SQL file.\u003c/p\u003e\n"],["\u003cp\u003eAfter migration, users must update and unpause Airflow DAGs, validate the new v5.0 reporting deployment, and then optionally delete old DAG tables using a provided \u003ccode\u003ejinja\u003c/code\u003e command, ensuring backups are taken beforehand as this step is irreversible.\u003c/p\u003e\n"]]],[],null,["# External DAGs migration from v4.2 to v5.0\n=========================================\n\n| **Warning:** This page contains specific information to update only Google Cloud Cortex Framework versions 4.2 to 5.0. The content might not apply to other versions.\n\nThis guide outlines the steps necessary to relocate output tables from external\nDirected Acyclic Graphs (DAGs) to their new locations within the Cortex Data\nFoundation v5.0 architecture. For example, Weather and Trends. This guide is\nspecifically designed for users who have implemented External DAGs in previous\nCortex Framework Data Foundation versions (4.2 to 5.0) and are now upgrading. If\nyou haven't used External DAGs or haven't deployed SAP, this guide is not\napplicable.\n\nContext\n-------\n\nCortex Framework Data Foundation versions prior to 4.2 used a `_GEN_EXT` flag to manage\nthe deployment of external data sources, with some sources tied to specific\nworkloads (like currency conversion for SAP). However, with version 5.0, this\nflag has been removed. Now, there's a new module dedicated to managing DAGs\nthat can serve multiple workloads. This guide outlines steps to adjust your\nexisting data pipelines to work with this new structure.\n\n### Cross-workload reusable DAGs\n\nCortex Framework Data Foundation v5.0 introduces K9, a new component responsible for\ningesting, processing, and modeling reusable data elements that are shared\nacross various data sources. Reporting views are now reference the\n`K9_PROCESSING` dataset to access these reusable components, streamlining data\naccess and reducing redundancy. The following external data sources are now\ndeployed as a part of K9, into the `K9_PROCESSING` dataset:\n\n- `date_dimension`\n- `holiday_calendar`\n- `trends`\n- `weather`\n\n### SAP-dependent DAGs\n\nThe following SAP-dependent DAGs are still triggered by\n`generate_external_dags.sh` script, but now executes during the reporting build\nstep, and now write into the SAP reporting dataset instead of the CDC\n(Change Data Capture) stage.\n\n- `currency_conversion`\n- `inventory_snapshots`\n- `prod_hierarchy_texts`\n\nMigration Guide\n---------------\n\nThis guide outlines the steps to upgrade your Cortex Framework Data Foundation to version 5.0.\n\n### Deploy Cortex Framework Data Foundation 5.0\n\nFirst, deploy the newest version (v5.0) of Cortex Framework Data Foundation to your\nprojects, with the following guidelines:\n\n1. Use your existing RAW and CDC datasets from prior development or staging deployments as your RAW and CDC datasets of this deployment, as no modification is made to them during deployment.\n2. Set both `testData` and `SAP.deployCDC` to `False` in `config/config.json`.\n3. Create a new SAP Reporting project separate from your existing v4.2 environment for testing purposes. This safely evaluate the upgrade process without impacting your current operations.\n4. Optional. If you have active Airflow DAGs running for your previous Cortex Framework Data Foundation version, pause them before proceeding with the migration. This can be done through the Airflow UI. For detailed instructions see [Open Airflow UI from Composer](/composer/docs/how-to/accessing/airflow-web-interface) and [Pause the DAG](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html#dag-pausing-deactivation-and-deletion) documentation.\n\nBy following these steps, you can safely transition to Cortex Framework Data Foundation\nversion 5.0 and validate the new features and functionalities.\n\n### Migrate existing tables\n\nTo migrate your existing tables to their new location, use `jinja-cli` to\nformat the provided migration script template to complete the migration.\n\n1. Install jinja-cli with the following command:\n\n pip install jinja-cli\n\n2. Identify the following parameters from your existing version 4.2 and new\n version 5.0 deployment:\n\n3. Create a JSON file with the required input data. Make sure to remove any\n DAGs you don't want to migrate from the `migrate_list` section:\n\n {\n \"project_id_src\": \"your-source-project\",\n \"project_id_tgt\": \"your-target-project\",\n \"dataset_cdc_processed\": \"your-cdc-processed-dataset\",\n \"dataset_reporting_tgt\": \"your-reporting-target-dataset-OR-SAP_REPORTING\",\n \"k9_datasets_processing\": \"your-k9-processing-dataset-OR-K9_REPORTING\",\n \"migrate_list\":\n [\n \"holiday_calendar\",\n \"trends\",\n \"weather\",\n \"currency_conversion\",\n \"inventory_snapshots\",\n \"prod_hierarchy_texts\"\n ]\n }\n EOF\n\n For example, if you want to remove `weather` and `trends`, the script would\n look like the following: \n\n {\n \"project_id_src\": \"kittycorn-demo\",\n \"project_id_tgt\": \"kittycorn-demo\",\n \"dataset_cdc_processed\": \"CDC_PROCESSED\",\n \"dataset_reporting_tgt\": \"SAP_REPORTING\",\n \"k9_datasets_processing\": \"K9_PROCESSING\",\n \"migrate_list\":\n [\n \"holiday_calendar\",\n \"currency_conversion\",\n \"inventory_snapshots\",\n \"prod_hierarchy_texts\"\n ]\n }\n\n4. Create an output folder with the following command:\n\n mkdir output\n\n5. Generate the parsed migration script with the following command (this command\n assumes you are at the root of the repository):\n\n jinja -d data.json -o output/migrate_external_dags.sql docs/external_dag_migration/scripts/migrate_external_dags.sql\n\n6. Examine the output SQL file and execute in BigQuery to migrate your tables to the new location.\n\n### Update and unpause the Airflow DAGs\n\nBack up the current DAG Files in your Airflow bucket. Then, replace them with\nthe newly generated files from your Cortex Framework Data Foundation version 5.0\ndeployment. For detail instructions, see the following documentation:\n\n- [Open Airflow UI from Composer](/composer/docs/how-to/accessing/airflow-web-interface)\n- [Unpause the DAG](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html#dag-pausing-deactivation-and-deletion)\n\n### Validation and cleanup\n\nThe migration is now complete. You can now validate that all reporting views\nin the new v5.0 reporting deployment is working correctly. If everything works\nproperly, go through the process again, this time targeting the v5.0 deployment\nto your production Reporting set. Afterwards, feel free to remove all tables\nusing the following script:\n**Warning:** This step permanently removes your old DAG tables and can't be undone after is applied. Only execute this step after all validation is complete. Consider taking backups of these tables. \n\n jinja -d data.json -o output/delete_old_dag_tables.sql docs/external_dag_migration/scripts/delete_old_dag_tables.sql"]]
