升级建议

本页介绍了从自定义 Cortex Framework Data Foundation 升级到新版本的建议。每次发布时，Cortex 团队都会承诺在向 Cortex Framework 添加新功能的同时，尽可能减少中断。新更新优先考虑向后兼容性。不过，本指南可帮助您最大限度地减少可能出现的问题。

Cortex Framework Data Foundation 提供了一组预定义的内容和模板，可帮助您更快地从复制到 BigQuery 的数据中发掘价值。组织可以根据自己的需求调整这些模板、模块、SQL、Python 脚本、流水线和其他提供的内容。

核心组件

Cortex Framework Data Foundation 内容的设计理念是开放性。组织可以根据自己的需求选择最适合的工具来处理所提供的 BigQuery 数据模型。基础紧密依赖的唯一平台是 BigQuery。所有其他工具都可以根据需要互换：

数据集成：任何与 BigQuery 具有互连性的集成工具都可以使用，前提是该工具能够复制原始表和结构。例如，原始表应与在 SAP 中创建时具有相同的架构（相同的名称、字段和数据类型）。此外，集成工具还应能够提供基本转换服务，例如更新目标数据类型以实现 BigQuery 兼容性，以及添加时间戳或操作标志等其他字段来突出显示新记录和更改的记录。
数据处理：变更数据捕获 (CDC) 处理脚本可与 Managed Service for Apache Airflow（或 Apache Airflow）搭配使用，但并非必需。反之，SQL 语句会尽可能与 Airflow 特有的文件分开生成，以便客户可以在其他工具中根据需要使用单独的 SQL 文件。
数据可视化：虽然我们提供了 Looker 信息中心模板，其中包含可视化图表和最少的逻辑，但核心逻辑仍保留在 BigQuery 内的数据基础中，以便用户使用自己选择的报告工具创建可视化图表。

主要优势

Cortex Framework 数据基础旨在适应各种业务需求。其组件具有灵活性，可让组织根据自身特定要求定制平台，并获得以下优势：

开放性：除了 BigQuery 之外，还可与各种数据集成、处理和可视化工具无缝集成。
自定义：组织可以修改和扩展预构建的组件（例如 SQL 视图），以匹配其数据模型和业务逻辑。
性能优化：可以根据各个工作负载和数据量调整分区、数据质量检查和聚簇等技术。
向后兼容性：Cortex 力求在未来的版本中保持向后兼容性，尽可能减少对现有实现的影响。如需了解版本变更，请参阅版本说明。
社区贡献：鼓励用户分享知识和协作。

更新进程

以下部分介绍了开发者可以采用的一种方法，以便在保留自定义项的同时，让自己的代码与 Cortex Framework Data Foundation 代码库保持同步。在 CI/CD 流水线中使用预交付的部署脚本。不过，组织可以采用其他工具和方法来满足自己的偏好，例如 Dataform 或不同 Git 托管服务（例如 GitHub Actions）提供的自动化工具。

设置代码库

本部分概述了一种设置代码库的方法。在执行这些步骤之前，建议您先扎实掌握 Git 知识。

派生核心代码库：创建 Cortex Framework Data Foundation 代码库的派生版本。该派生版本会使相应代码库继续接收来自 Google Cloud 代码库的更新，并为公司的主代码库提供单独的代码库。
创建公司代码库：为公司的代码库（例如 Cloud Source）建立新的 Git 托管服务。在新主机上创建一个与派生代码库同名的代码库。
初始化公司代码库：将您派生的代码库中的代码复制到新创建的公司代码库中。使用以下命令将原始派生代码库添加为上游远程代码库，并验证远程代码库是否已添加。这会在公司代码库和原始代码库之间建立连接。
```
git remote add google <<remote URL>>
git remote -v
git push --all google
```
验证代码库设置：确保公司代码库包含克隆的代码和历史记录。您应该会看到两个远程库，即 origin 和您在使用命令后添加的远程库：
```
git remote -v:
```
现在，您已经拥有了代码库（即公司代码库），开发者可以在其中提交更改。开发者现在可以克隆新代码库中的分支并进行相关工作。

将您的更改与新的 Cortex 版本合并

本部分介绍如何合并来自公司代码库的更改和来自 Google Cloud 代码库的更改。

更新派生版本：点击同步派生版本，以使用 Google Cloud 代码库中的更改更新您的代码库的派生版本。例如，对公司代码库进行了以下更改。此外， Google Cloud 还在新版本中对 Data Foundation 代码库进行了一些其他更改。
- 在 SQL 中创建并纳入了新视图的使用
- 修改了现有视图
- 完全使用我们自己的逻辑替换了某个脚本
以下命令序列会将派生代码库添加为上游远程代码库，以便从 GitHub 中拉取更新后的版本，并将其主分支签出为 GitHub-main。然后，此示例从 Google Cloud 来源的公司代码库中检出主分支，并创建一个用于合并的分支 merging_br。
```
git remote add github <<github fork>>
git fetch github main
git checkout -b github-main github/main
git checkout  main
git checkout -b merging_br
```
您可以通过多种方式构建此流程。合并过程也可以在 GitHub 的 fork 中进行，也可以通过 rebase（而非合并）来替换，并且合并分支也可以作为合并请求发送。这些流程变体取决于当前的组织政策、更改的深度和便利性。

完成此设置后，您可以将传入的更改与本地更改进行比较。建议您使用所选图形 IDE 中的工具来查看更改并选择要合并的内容。例如，Visual Studio。

建议使用醒目的注释标记自定义项，以便更轻松地进行差异比较。
开始合并流程：使用创建的分支（在本示例中，该分支名为 merging_br）来合并所有更改并舍弃文件。准备就绪后，您可以将此分支合并回公司代码库的主分支或其他分支，以创建合并请求。从公司代码库的主分支 (git checkout merging_br) 中检出的合并分支中，合并来自远程 Fork 的传入更改。
```
    ## git branch -a
    ## The command shows github-main which was created from the GitHub fork
    ## You are in merging_br

    git merge github-main

    ## If you don't want a list of the commits coming from GitHub in your history, use `--squash`
```
此命令会生成冲突列表。使用图形化 IDE 比较来了解更改，并在当前、传入和两者之间进行选择。此时，在代码中添加有关自定义的注释就非常有用。您可以选择完全舍弃更改，删除您不想合并的文件，并忽略对已自定义的视图或脚本的更改。

合并更改：确定要应用的更改后，查看摘要并使用以下命令提交更改：

    git status
    ## If something doesn't look right, you can use git rm or git restore accordingly
    git add --all #Or . or individual files
    git commit -m "Your commit message"

如果您对任何步骤感到不安全，请参阅 Git 基本撤消操作。

测试和部署：到目前为止，您只是合并到“临时”分支中。建议此时运行 cloudbuild\*.yaml 脚本中的测试部署，以确保一切按预期执行。自动化测试有助于简化此流程。如果此合并分支看起来没问题，您可以结账主目标分支，然后将 merging_br 分支合并到其中。