Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Migração de DAGs externos da versão 4.2 para a 5.0
Este guia descreve os passos necessários para mudar as tabelas de saída de grafos acíclicos dirigidos (DAGs) externos para as respetivas novas localizações na arquitetura da Cortex Data Foundation v5.0. Por exemplo, meteorologia e tendências. Este guia foi
concebido especificamente para utilizadores que implementaram DAGs externos em versões
anteriores da base de dados do framework Cortex (4.2 a 5.0) e que estão a fazer a atualização. Se não usou DAGs externos ou não implementou o SAP, este guia não é aplicável.
Contexto
As versões da base de dados do Cortex Framework anteriores à 4.2 usavam uma flag _GEN_EXT para gerir a implementação de origens de dados externas, com algumas origens associadas a cargas de trabalho específicas (como a conversão de moeda para o SAP). No entanto, com a versão 5.0, esta flag foi removida. Agora, existe um novo módulo dedicado à gestão de DAGs que podem processar várias cargas de trabalho. Este guia descreve os passos para ajustar os pipelines de dados existentes de modo a funcionarem com esta nova estrutura.
DAGs reutilizáveis em várias cargas de trabalho
A Data Foundation v5.0 do Cortex Framework introduz o K9, um novo componente responsável por
carregar, processar e modelar elementos de dados reutilizáveis que são partilhados
em várias origens de dados. As visualizações de relatórios referem-se agora ao conjunto de dados K9_PROCESSING para aceder a estes componentes reutilizáveis, simplificando o acesso aos dados e reduzindo a redundância. As seguintes origens de dados externos são agora implementadas como parte do K9 no conjunto de dados K9_PROCESSING:
date_dimension
holiday_calendar
trends
weather
DAGs dependentes do SAP
Os DAGs dependentes do SAP seguintes ainda são acionados pelo script generate_external_dags.sh, mas agora são executados durante o passo de compilação de relatórios e escrevem no conjunto de dados de relatórios do SAP em vez da fase de CDC (captura de dados de alterações).
currency_conversion
inventory_snapshots
prod_hierarchy_texts
Guia de migração
Este guia descreve os passos para atualizar a base de dados do Cortex Framework para a versão 5.0.
Implemente a base de dados do Cortex Framework 5.0
Primeiro, implemente a versão mais recente (v5.0) da base de dados do Cortex Framework nos seus projetos, seguindo estas diretrizes:
Use os seus conjuntos de dados RAW e CDC existentes de implementações de desenvolvimento ou de preparação anteriores como os conjuntos de dados RAW e CDC desta implementação, uma vez que não são feitas modificações aos mesmos durante a implementação.
Defina testData e SAP.deployCDC como False em config/config.json.
Crie um novo projeto de relatórios SAP separado do seu ambiente v4.2 existente para fins de teste. Isto permite avaliar em segurança o processo de atualização sem afetar as suas operações atuais.
Opcional. Se tiver DAGs do Airflow ativos em execução para a versão anterior da base de dados do Cortex Framework, pause-os antes de continuar com a migração.
Pode fazê-lo através da IU do Airflow. Para obter instruções detalhadas, consulte a documentação
Abra a IU do Airflow a partir do Composer
e Pause o DAG.
Seguindo estes passos, pode fazer a transição em segurança para a versão 5.0 da Data Foundation do Cortex Framework e validar as novas funcionalidades.
Migre tabelas existentes
Para migrar as tabelas existentes para a nova localização, use jinja-cli para formatar o modelo de script de migração fornecido para concluir a migração.
Instale o jinja-cli com o seguinte comando:
pipinstalljinja-cli
Identifique os seguintes parâmetros da sua implementação da versão 4.2 existente e da nova versão 5.0:
Nome
Descrição
project_id_src
Google Cloud Projeto: projeto onde se encontra o seu conjunto de dados do SAP CDC existente
da implementação da versão 4.2. O conjunto de dados K9_PROCESSING também é criado neste projeto.
project_id_tgt
Segmente Google Cloud onde se encontra o conjunto de dados de relatórios SAP recém-implementado da implementação da nova versão 5.0. Pode ser
diferente do projeto de origem.
dataset_cdc_processed
Conjunto de dados do BigQuery da CDC:
Conjunto de dados do BigQuery onde os dados processados da CDC são carregados com os
registos mais recentes disponíveis. Este pode ser o mesmo que o conjunto de dados de origem.
dataset_reporting_tgt
Conjunto de dados de relatórios do BigQuery de destino: conjunto de dados do BigQuery onde os modelos de dados predefinidos da base de dados de dados para SAP são implementados.
k9_datasets_processing
Conjunto de dados do BigQuery do K9:
conjunto de dados do BigQuery onde o K9 (origens de dados aumentadas) está implementado.
Crie um ficheiro JSON com os dados de entrada necessários. Certifique-se de que remove todos os DAGs que não quer migrar da secção migrate_list:
Examine o ficheiro SQL de saída e execute-o no BigQuery para migrar as tabelas para a nova localização.
Atualize e retome os DAGs do Airflow
Faça uma cópia de segurança dos ficheiros DAG atuais no seu contentor do Airflow. Em seguida, substitua-os pelos ficheiros gerados recentemente a partir da implementação da versão 5.0 da Data Foundation do Cortex Framework. Para ver instruções detalhadas, consulte a seguinte documentação:
A migração está agora concluída. Agora, pode validar se todas as vistas de relatórios
na nova implementação de relatórios v5.0 estão a funcionar corretamente. Se tudo funcionar corretamente, repita o processo, desta vez segmentando a implementação da versão 5.0 para o conjunto de relatórios de produção. Depois, pode remover todas as tabelas
com o seguinte script:
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-21 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"]]
