部署配置

本文档介绍了 Cortex Framework 在以下方面的部署配置选项:

本指南还提供了操作指南,其中包含针对常见部署用例和场景的分步说明。

配置文件:config/config.yaml

config/config.yaml 文件(通常从 config/config.yaml.example 模板初始化)用作 Cortex Framework 部署的主要配置。它定义了关键参数,包括目标 Google Cloud 执行项目、源和目标 BigQuery 数据集,以及 Dataform 规范(例如代码库和工作区名称)。

以下各部分详细介绍了 config/config.yaml 结构。

构建环境

构建环境项目是指因构建操作(例如 BigQuery 作业 [读取 DD03L])而产生费用的项目。

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

下表介绍了构建环境参数。

参数 含义 默认值 说明
buildEnvironment.buildProjectId build 项目 ID YOUR_BUILD_PROJECT_ID Google Cloud 执行 build 操作的项目 ID。

“数据”部分概览

配置文件的 data: 部分用于定义数据源、目标以及数据基础和数据产品的特定模块。 其一般结构如下:

data:
   # Geographic location for BigQuery datasets (for example: US, EU, us-central1)
   # For full list see: https://docs.cloud.google.com/cortex/docs/supported-locations
  bigQueryLocation: US
  # List of namespaces for data foundation and product modules.
  namespaces:
    - name: cortex
      path: cortex
  # List of source datasets.
  sources:
    - ...
  # List of target datasets.
  targets:
    - ...

  # Configuration for data foundation and product modules.
  modules:
    # List of foundation modules.
    foundation:
    - ... 
    # List of data product modules.
    product:
    - ...

数据:BigQuery 位置

定义 BigQuery 源数据集和目标数据集的位置。

参数 含义 默认值 说明
data.bigQueryLocation BigQuery 位置 US BigQuery 数据集位置(例如 USus-central1europe-west1)。

数据:Cortex 命名空间

定义 Cortex Framework 命名空间。

参数 含义 默认值 说明
data.namespaces.name 命名空间名称 - Cortex Framework 命名空间名称。例如 cortex
data.namespaces.path 命名空间路径 - 用于 src 和 config 文件夹中的子目录的 Cortex Framework 命名空间路径。例如 cortex

数据:BigQuery 来源和目标数据集

来源列表定义了 BigQuery 数据集,其中包含已从源系统复制或流式传输到其中的原始数据。

目标定义了将存储 Dataform 处理后的数据集的 BigQuery 数据集列表。

每个来源和目标都通过其唯一 ID 从模块中引用。

# Data source and target mapping
sources:
  - id: sap_raw
    projectId: YOUR_SOURCE_PROJECT_ID
    datasetId: cortex_sap_raw

targets:
  - id: sap_foundation
    projectId: YOUR_TARGET_PROJECT_ID
    datasetId: cortex7_sap_data_foundation

下表介绍了数据源和目标映射参数。

参数 含义 默认值 说明
data.sources.id Source ID(来源 ID) - 定义要从中提取数据的源数据集的“id”。例如 sap_raw
data.sources.projectId 源项目 ID YOUR_SOURCE_PROJECT_ID 引用包含源数据的 Google Cloud 项目 ID。
data.sources.datasetId 源 BigQuery 数据集 ID - 引用包含源数据的 BigQuery 数据集 ID。例如 cortex_sap_raw
data.targets.id 定位条件ID - 定义目标数据集的“id”。例如 sap_foundation
data.targets.projectId 目标项目 ID YOUR_TARGET_PROJECT_ID 引用目标数据的 Google Cloud 项目 ID。
data.targets.datasetId 目标 BigQuery 数据集 ID - 引用目标数据的 BigQuery 数据集 ID。例如 cortex7_sap_data_foundation

数据:模块

模块定义了 Dataform 数据流水线的结构和组件。

数据:模块:基础

此部分配置了数据基础层模块,这些模块可将原始层(CDC 流)中的数据处理为源数据的标准化最新记录表示形式。如果源直接提供最新记录的视图,或者此类转换由源系统连接器执行,则可以将模块配置为外部数据基础源。

modules:
  # List of foundation modules.
  foundation:
    # Unique identifier for the module instance.
    - moduleId: erp
      # Type of the module (namespaced, for example, cortex.sap).
      type: cortex.sap
      # Reference to the source dataset ID.
      dataSourceId: sap_raw
      # Reference to the target dataset ID.
      dataTargetId: sap_foundation
      # Module-specific configuration settings.
      moduleSettings:
        # SAP version (for example, ecc, s4).
        sapVersion: ecc
        # SAP client number.
        mandt: "100"
      # Whether the module is enabled.
      # enabled: true
      # Whether the foundation is external (does not create target dataset).
      # external: false
      # Custom table settings file, relative to 'config/' file directory
      # Recommended path: '{namespace}/data_foundation/{data_foundation_module_type}/table_settings.yaml'
      # Default path: '../src/data_modules/{namespace}/data_foundation/{data_foundation_module_type}/table_settings.default.yaml'
      # tableSettings: "custom_datafoundation_table_settings.yaml"

下表介绍了 modules.foundation 配置的数据基础模块参数。

参数 含义 默认值 说明
moduleId 模块标识符 erp 特定数据基础转换模块实例的唯一标识符。
type 模块逻辑类型 cortex.sap 定义应用的业务逻辑或模板(例如 cortex.sap)。
dataSourceId 来源链接 sap_raw 引用 data.sources 列表中的“id”以从中提取数据。
dataTargetId 目标链接 sap_foundation 引用目标列表中的“id”,以将数据推送到该目标。
moduleSettings.sapVersion SAP 系统版本 ecc 仅适用于 SAP 数据源。确定 ecc (ECC) 或 s4 (S/4HANA) 系统的特定于来源的逻辑。
moduleSettings.mandt SAP 客户端 (Mandant) 100 仅适用于 SAP 数据源。用于过滤数据行的 3 位数 SAP 客户端标识符。
enabled 模块启用 true 指定模块是否已启用。
external 外部基金会 false 指定基础是否为外部基础(不创建目标数据集)。
tableSettings 表设置 src/data_modules/{namespace}/data_foundation/{data_foundation_module_type}/table_settings.default.yaml 自定义表格设置配置文件的路径(相对于此配置文件)。
推荐路径:相对于 `config/` 目录:'{namespace}/data_foundation/{data_foundation_module_type}/table_settings.yaml'
默认路径:'../src/data_modules/{namespace}/data_foundation/{data_foundation_module_type}/table_settings.default.yaml'

数据:模块:商品

数据产品模块定义了将原始数据转换为可满足特定业务应用场景的数据洞见所需的汇总、计算和联接。

数据产品的配置允许设置唯一 ID、定义依赖项,以及引用数据基础模块和将存储结果的目标数据集。

给定数据产品的详细配置在由键 tableSettings 引用的文件中定义。

modules:
  # List of data product modules.
  product:
    # Unique identifier for the data product instance.
    - moduleId: sap_purchasing_organizational_structure
      # Type of the data product (namespaced).
      type: cortex.purchasing_organizational_structure
      # Map of module dependencies.
      dependsOn:
        sapModule: erp
      # Reference to the target dataset ID.
      dataTargetId: product_target
      # Whether the module is enabled.
      # enabled: true

      # Custom table settings file, relative to 'config/' file directory
      # Recommended path: '{namespace}/data_product/{data_product_module_type}/table_settings.yaml'
      # If omitted, defaults to '../src/data_modules/{namespace}/data_product/{data_product_module_type}/table_settings.default.yaml'
      # tableSettings: "custom_dataproduct_table_settings.yaml"

下表介绍了 modules.product 配置的数据产品模块参数。

参数 含义 默认值 说明
moduleId 模块标识符 - 特定转换模块实例的唯一标识符。
type 模块逻辑类型 - 定义应用的业务逻辑或模板,在 src/data_modules/{namespace}/data_product/{data_product_module_type} 文件夹中定义。
dataTargetId 目标链接 product_target 引用目标列表中的“id”,以将数据推送到该目标。
dependsOn 上游依赖项 sapModule: erp 指定在构建产品模块之前必须存在的基础模块。
enabled 模块启用 true 指定模块是否已启用。
tableSettings 表设置 src/data_modules/{namespace}/data_product/{data_product_module_type}/table_settings.default.yaml 自定义表格设置配置文件的路径(相对于此配置文件)。
推荐路径:相对于 `config/` 目录:'{namespace}/data_product/{data_product_module_type}/table_settings.yaml'
默认路径:'../src/data_modules/{namespace}/data_product/{data_product_module_type}/table_settings.default.yaml'

部署环境

Cortex Framework 使用 Dataform 来编排 BigQuery 中的 SQL 转换。deployment: 块用于定义 Dataform 配置,负责执行数据流水线,包括仓库项目、位置、仓库名称和 Dataform 工作区名称。

deployment:
  targets:
    - type: dataform
      enabled: true
      targetSettings:
        repositoryProjectId: YOUR_REPO_PROJECT_ID
        repositoryRegion: us-central1
        repositoryName: cortex-repository
        workspaceName: dev
        # serviceAccount: "example@example.com"

下表介绍了部署目标位置参数 (deployment.targets:)。

参数 含义 默认值 说明
type 部署类型 dataform 部署目标的类型。
enabled 已启用/ 已停用 true 指定给定的部署目标是处于启用状态还是处于停用状态。
targetSettings.repositoryProjectId 代码库项目 ID YOUR_REPO_PROJECT_ID 管理 Dataform 代码库的 Google Cloud 项目 ID。
targetSettings.repositoryRegion 代码库区域 us-central1 Dataform 代码库的 Google Cloud 区域(例如 us-central1europe-west1)。
targetSettings.repositoryName 代码库名称 cortex-repository Dataform 代码库的具体名称。
targetSettings.workspaceName 工作区名称 dev 用于部署周期的特定 Dataform 工作区。
targetSettings.serviceAccount 服务账号电子邮件地址 - 用于 Dataform 代码库执行的默认服务账号电子邮件地址。

配置文件:table_settings.yaml

本指南介绍了如何使用 table_settings.yaml 文件在 Google Cloud Cortex Framework 中配置数据基础表和数据产品表。

特定于数据模块的 table_settings.yaml 文件用于控制原始源表的规范化方式以及分析数据模型在 BigQuery 中的具体化方式。您可以使用此文件配置标记、具体化策略和高级 BigQuery 性能功能,例如分区或聚类。

动态依赖项解析

默认情况下,Cortex Framework 仅部署和编译作为已启用数据产品的依赖项所需的基础表,从而优化部署占用空间和执行时间。如果 table_settings.yaml 中配置的表没有任何依赖它的有效下游数据产品,则会从部署中省略该表。

如需替换此优化并强制部署基础表,您可以将 deployAlways 属性设置为 true(请参阅数据基础样式参数参考)。

在 Google Cloud Cortex Framework 中,每个模块(基础或产品)都可以在部署配置文件中分配一个特定的表格设置文件:config/config.yaml 使用 tableSettings 属性。

配置路径

  • 自定义设置(推荐):如需自定义表格行为,请将默认文件复制到您的配置目录,对其进行修改,然后在 config/config.yaml 中引用其路径。建议使用的路径(相对于 config/ 目录)如下:
    • 基础模块namespace/data_foundation/data_foundation/custom_table_settings.yaml(例如,config/cortex/data_foundation/sap/table_settings.yaml
    • 产品模块namespace/data_product/data_product/custom_table_settings.yaml(例如,config/cortex/data_product/accounting_documents/table_settings.yaml
  • 默认回退:如果省略 tableSettings,框架会自动回退到:
    • 基础模块../src/data_modules/namespace/data_foundation/data_foundation/table_settings.default.yaml
    • 产品模块../src/data_modules/namespace/data_product/data_product/table_settings.default.yaml

配置样式

table_settings.yaml 有两种不同的架构样式,具体取决于模块的类别:

  1. 数据基础样式:基于列表的映射,用于定义源到目标的架构关系、CDC(变更数据捕获)处理和 BigQuery 布局。
  2. 数据产品样式:基于地图的映射(字典),用于定义如何具体化(例如作为视图、表或增量表)和优化分析视图或表。

这两种样式都支持三个根级部分,用于按源系统版本(主要用于 SAP Data Foundation 和依赖于 SAP 的产品)分隔配置:

  • ecc:仅在部署 SAP ECC 源系统时应用的设置。
  • s4:仅在部署 SAP S/4HANA 源系统时应用。
  • common:无论 SAP 版本如何,都会应用设置(用于一致或通用设置)。

数据基础样式

在 Data Foundation 模块中,table_settings.yaml 文件的结构为 eccs4common 键下的表项列表。每个项都会将原始源表映射到一致的目标表,并配置其 BigQuery 设置。

YAML 语法示例

common:
  - source:
      tableName: bkpf
      isCdc: true
    target:
      tableName: bkpf # Optional: defaults to source tableName if omitted
      tags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day
    deployAlways: false

参数引用

参数 类型 必需 默认 / 示例 说明
ecc | s4 | common string [] 源系统版本或方言。
[].deployAlways boolean false 如果值为 true,则始终会部署和构建表,即使优化规则可能会跳过该表。另请参阅动态依赖项解析
来源设置

定义原始入站表的特征。

参数 类型 必需 默认 / 示例 说明
tableName string bkpf BigQuery 中原始源表的名称(不区分大小写)。
isCdc boolean true 指示源表是否包含变更数据捕获 (CDC) 日志。

true(默认):框架会处理 CDC 日志(使用记录时间戳和操作标志)来重建最新的规范化状态。

false:系统会将相应表作为完整快照进行处理。

目标设置

定义目标数据集中的输出一致化表布局。

参数 类型 必需 默认 / 示例 说明
tableName string *(与来源相同)* 要创建的目标一致性表的名称。如果省略,框架会默认使用来源 tableName
tags array[string] [sap, finance] 附加到 Dataform 中已规范化操作的元数据标记列表。这些是任意字符串,无需预先注册或在其他配置中定义;它们可立即用于过滤流水线执行(例如,使用 dataform run --tags ...)。
clusterDetails map 可选。BigQuery 聚簇配置。请参阅聚类详细信息
partitionDetails map 可选。BigQuery 分区配置。请参阅分区详细信息

数据产品样式

在数据产品模块中,table_settings.yaml 文件在 eccs4common 键下以字典(映射)的形式结构化。字典的键表示分析表或视图名称,值定义了它们的具体化和性能设置。

YAML 语法示例

s4:
  customers:
    materializationType: incremental
    tags: [sap, dataproduct, masterdata]
    clusterDetails:
      columns: [mandt, ktokd]

参数引用

参数 类型 必需 默认 / 示例 说明
ecc | s4 | common map {} 目标分析型资产(表或视图)与其配置的映射。
[table_name].materializationType string incremental 如何在 BigQuery 中构建分析型资产。

允许的值

  • incremental:仅处理自上次运行以来新增或更新的记录。建议用于大型事务性数据集,以节省费用。
  • table:在每次运行时从头开始完全重建表。
  • view:将资产部署为 BigQuery SQL 视图(虚拟表)。
[table_name].tags array[string] [sap, dataproduct] 附加到 Dataform 中分析资产的元数据标记。这些是任意字符串,无需预先注册;它们可立即用于选择性流水线运行。
[table_name].clusterDetails map 可选。BigQuery 聚簇配置。请参阅聚类详细信息
[table_name].partitionDetails map 可选。BigQuery 分区配置。请参阅分区详细信息

高级 BigQuery 配置

这两种样式都具有相同的结构,可通过聚簇分区来优化 BigQuery 存储和查询性能。


聚类详细信息

聚簇会根据特定列中的值共置数据。BigQuery 会使用这些列对每个存储块中的数据进行排序,从而大幅加快对这些列进行过滤 (WHERE) 或联接 (JOIN) 的查询。

clusterDetails:
  columns: [bukrs, gjahr]
参数引用
参数 类型 必需 示例 说明
columns array[string] [bukrs, gjahr] 用于对表进行聚簇的列名称的有序列表(最多包含 4 个列名称)。

限制:列必须是字母数字,并且只能包含下划线。列表中的列顺序决定了排序层次结构。


分区详细信息

分区会根据日期、时间戳或整数列的值,将大型表划分为多个较小的物理分段。这样可防止 BigQuery 在查询仅请求特定范围的日期、月份或 ID 时扫描整个表。

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
参数引用
参数 类型 必需 示例 说明
column string budat 用于对表进行分区的列的名称。只能包含字母数字字符和下划线。列类型必须与 partitionType 相匹配。
partitionType string time 划分策略。

允许的值

  • time:按时间单位(日期、时间戳或日期时间列)进行分区。
  • DATE:按日期列显式分区。
  • integer:按整数范围进行分区。
timeGrain string day 如果 partitionTypetimeDATE,则为必需。定义时间分区的粒度。

允许的值hourdaymonthyear(不区分大小写)。

rangeStart integer 1 如果 partitionTypeinteger,则必须提供此值。第一个分区的起始值(含边界值)。
rangeEnd integer 1000 如果 partitionTypeinteger,则必须提供此值。最后一个分区的结束值(不含)。
rangeInterval integer 10 如果 partitionTypeinteger,则必须提供此值。每个分区区间的宽度。

示例

以下示例展示了数据基础模块和数据产品模块的配置模板,概述了如何自定义目标表、优化 BigQuery 中的存储布局以及配置具体化类型。

1. 自定义数据基础表格设置示例

此示例展示了如何配置一个基础层,其中包含聚簇和分区事务表(如 bsegekbe)以及标准数据表:

# ==============================================================================
# S/4HANA-Specific Tables
# ==============================================================================
s4:
  # ACDOCA is a massive table in S/4HANA; clustering is vital
  - source:
      tableName: acdoca
    target:
      tags: [sap, s4, finance, transactional, hourly]
      clusterDetails:
        columns: [rclnt, rbukrs, gjahr]

# ==============================================================================
# ECC-Specific Tables
# ==============================================================================
ecc:
  - source:
      tableName: faglflexa
    target:
      tags: [sap, ecc, finance, transactional, hourly]

# ==============================================================================
# Common Tables (ECC & S/4HANA)
# ==============================================================================
common:
  # Financial document header (partitioned by posting date)
  - source:
      tableName: bkpf
      isCdc: true
    target:
      tags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day

  # Purchasing document items (partitioned by creation date)
  - source:
      tableName: ekpo
    target:
      tags: [sap, common, logistics, purchasing, hourly]
      clusterDetails:
        columns: [mandt, ebeln]
      partitionDetails:
        column: aedat
        partitionType: time
        timeGrain: month

  # Standard master data table (no partitioning/clustering needed)
  - source:
      tableName: lfa1
    target:
      tags: [sap, common, masterdata, vendor, daily]

2. 自定义数据商品表格设置示例

此示例展示了如何为下游分析数据产品配置实体化类型。我们将事务型 sales_documents 设置为增量,以优化 build 性能并节省费用,而 customers 等非事务型数据表则作为标准表进行 build:

# settings applied for both ECC and S/4HANA pipelines
common:
  # Transactional data product - incremental build
  sales_documents:
    materializationType: incremental
    tags: [sap, dataproduct, sales, transactional]
    clusterDetails:
      columns: [vkorg, vbeln]
    partitionDetails:
      column: audat
      partitionType: time
      timeGrain: day

  # Master data product - full table rebuild
  customers:
    materializationType: table
    tags: [sap, dataproduct, masterdata]
    clusterDetails:
      columns: [mandt, ktokd]

  # Aggregated reporting view - virtual view
  sales_performance_summary:
    materializationType: view
    tags: [sap, dataproduct, sales, reporting]

方法指南

本部分针对常见配置任务和自定义部署方案提供了分步指南。

在数据基础模块中自定义表范围

如需在现有数据基础模块中添加或移除表,而无需创建新模块或运行单独的流水线实例,请执行以下操作:

  • 将默认的 table_settings.default.yaml 配置复制到工作区配置目录(例如 config/cortex/data_foundation/sap/custom_table_settings.yaml)。
  • 在新文件中,根据需要添加自定义表格或移除 eccs4common 键下的未使用的标准表格:
common:
  - source:
      tableName: custom_table_name
    target:
      tags: [custom_tag]
  • 更新 config/config.yaml 以引用模块 tableSettings 属性下自定义表格设置的路径:
data:
  modules:
    foundation:
      - moduleId: erp
        type: cortex.sap
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace}/data_foundation/{data_foundation_module_type}/table_settings.yaml'
        tableSettings: 'cortex/data_foundation/sap/custom_table_settings.yaml'

配置数据基础模块的多个实例

如需部署同一模块类型的两个或更多个单独的流水线实例(例如,支持多个 SAP 实例、用于细分表、隔离环境或定位不同的目标数据集),请执行以下操作:

准备工作: * 确保源表存在于源原始数据集中。 * 确保已配置目标数据集架构。 * 使用 SAP 数据基础模块时,请验证元数据表 DD03L 是否包含您打算注入的自定义表的列和描述符信息。如需了解详情,请参阅 SAP ERP 要求

操作说明

  • config/config.yaml 文件中,在 data.targets 下添加目标配置,以定义每个流水线实例的目标数据集:
data:
  targets:
    - id: data_foundation_core
      projectId: target_project_id
      datasetId: data_foundation_sap_core
    - id: data_foundation_custom
      projectId: target_project_id
      datasetId: data_foundation_sap_custom
  • data.modules.foundation 列表下定义模块的多个实例。为每个实例提供唯一的 moduleId、自己的目标数据集 ID,以及可选的 tableSettings 配置:
data:
  modules:
    foundation:
      # Core SAP ERP foundation module instance
      - moduleId: erp_core
        type: cortex.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_core
        # If omitted, defaults to "../src/data_modules/{namespace}/data_foundation/{data_foundation_module_type}/table_settings.default.yaml"
        # tableSettings: "../src/data_modules/cortex/data_foundation/sap/table_settings.default.yaml"
      # Custom tables pipeline instance
      - moduleId: erp_custom
        type: cortex.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_custom
        # Custom table settings file, relative to configuration file directory
        # Recommended path: 'config/{namespace}/data_foundation/{data_foundation_module_type}/table_settings.yaml'
        tableSettings: "cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml"
  • 创建 config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml 文件,指定自定义范围。E.g.:
common:
  - source:
      tableName: custom_sap_table_name
    target:
      tags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day
  • 运行部署脚本 (uv run cortex-build-and-deploy) 以应用更改,然后按照部署后步骤中所述执行 Dataform 操作。