Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

部署配置

本页介绍了 Cortex Framework 在以下方面的部署配置选项：

部署配置 (config/config.yaml)：定义全局变量、构建环境和模块映射（数据基础和数据产品目标）。
表配置 (table_settings.yaml)：模块特定的性能和架构规范，概述了如何在 BigQuery 中编译和调整基本表。

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

配置文件：`config/config.yaml`

config/config.yaml 文件（通常从 config/config.yaml.example 模板初始化）用作 Cortex Framework 部署的主要配置。配置分为以下结构块：

构建环境 (buildEnvironment)：管理构建编排层，指定用于结算和执行中间元数据计算、数据库验证和架构查找的中心 Google Cloud 项目。
数据 (data)：管理逻辑数据架构。此块用于配置数据集位置、命名空间边界、原始提取源的连接详细信息、目标数据集，并注册数据模块实例（foundations、catalogs 和 products）。
部署 (deployment)：配置实体目标系统部署。它用于指定已编译的 SQLX/JS 转换流水线的部署位置，即 Dataform 代码库详细信息（项目 ID、位置、代码库名称和开发工作区）。

以下各部分详细介绍了每个块。

构建环境

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

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

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

参数	含义	默认值	说明
`buildEnvironment.buildProjectId`	构建项目 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: ../src/data_modules/cortex
  # List of datasets mapping.
  datasets:
    - ...

  # Configuration for data foundation, data product, and external catalog modules.
  modules:
    # List of foundation modules.
    foundations:
    - ... 
    # List of external catalog modules.
    catalogs:
    - ...
    # List of data product modules.
    products:
    - ...

数据：BigQuery 位置

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

参数	含义	默认值	说明
`data.bigQueryLocation`	BigQuery 位置	`US`	BigQuery 数据集位置（例如 `US`、`us-central1` 或 `europe-west1`）。

数据：Cortex 命名空间

定义 Cortex Framework 命名空间。

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

数据：BigQuery 源数据集和目标数据集

数据集列表定义了框架的入站原始数据连接点和出站存储位置。每个数据集都会注册一个映射到特定 Google Cloud 项目和 BigQuery 数据集的唯一标识符。

数据集通过其唯一 ID 从模块中引用。

# Dataset mapping
datasets:
  - id: sap_raw
    projectId: YOUR_SOURCE_PROJECT_ID
    datasetId: cortex_sap_raw
  - id: sap_foundation
    projectId: YOUR_TARGET_PROJECT_ID
    datasetId: cortex7_sap_data_foundation

下表介绍了数据集映射参数。

参数	含义	默认值	说明
`data.datasets.id`	数据集 ID	`-`	定义数据集的唯一标识符（例如 `sap_raw` 或 `sap_foundation`）。
`data.datasets.projectId`	项目 ID	`-`	引用托管数据集的 Google Cloud 项目 ID。
`data.datasets.datasetId`	BigQuery 数据集 ID	`-`	引用实际的 BigQuery 数据集名称。

数据：模块

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

数据：模块：基础知识

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

modules:
  # List of foundation modules.
  foundations:
    # Unique identifier for the module instance.
    - moduleId: erp
      # Path of the module format: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap}, for example, cortex.sap.foundations.sap.
      modulePath: cortex.sap.foundations.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_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml' (e.g. 'cortex/sap/foundations/sap/table_settings.yaml')
      # Default path: '../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'
      tableSettings: "custom_table_settings.yaml"

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

参数	含义	默认值	说明
`moduleId`	模块标识符	`erp`	特定数据基础转换模块实例的唯一标识符。
`modulePath`	模块路径	`cortex.sap.foundations.sap`	定义所应用模块、业务逻辑或模板的命名空间路径。格式：{namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap}（例如，`cortex.sap.foundations.sap`）。
`dataSourceId`	来源链接	`sap_raw`	引用 `data.datasets` 列表中的“id”以从中提取数据。
`dataTargetId`	目标链接	`sap_foundation`	引用 `data.datasets` 列表中的“id”，以将数据推送到该“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_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml`	自定义表格设置配置文件的路径（相对于此配置文件）。推荐路径：相对于 `config/` 目录：'{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml' 默认路径：'../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'

数据：模块：目录

借助外部 Lakehouse 目录，Cortex Framework 可以从 BigLake Delta Sharing 目录和共享中注入外部表，而无需物理清单。

modules:
  # List of external catalog modules.
  catalogs:
    # Unique identifier for the catalog.
    - id: sap_bdc_catalog
      # Type of the catalog.
      type: lakehouse_delta_share
      # Logical namespace prefixes bound by this catalog.
      bindsNamespaces: [sap_bdc]
      # Connection settings for the catalog.
      connectionSettings:
        # Unique identifier for the catalog.
        catalogId: sap_bdc_catalog
        # Unique identifier for the project hosting the catalog.
        projectId: sap_bdc_delta_share
        # Geographic region location for the catalog.
        location: europe-west3
        # List of shares to import.
        shares:
          - shareId: customer_v1_he2_100_p8123
          - shareId: salesorder_v1_he2_100_p8124
      # Whether the catalog is enabled.
      # enabled: true

下表介绍了外部目录配置参数。

参数	含义	默认值	说明
`id`	目录标识符	-	特定外部目录模块实例的唯一标识符。
`type`	目录类型	`lakehouse_delta_share`	目录的类型。支持 `lakehouse_delta_share`。
`bindsNamespaces`	已绑定的命名空间	-	此目录绑定的逻辑命名空间前缀的列表（例如 `[sap_bdc]`）。
`connectionSettings.catalogId`	实体目录 ID	-	实体目录 ID。通常与模块 ID 相同。
`connectionSettings.projectId`	项目 ID	-	管理目录连接的 Google Cloud 项目 ID。
`connectionSettings.location`	位置	-	目录的地理区域位置。
`connectionSettings.shares`	共享	-	要导入的 Delta Sharing 共享的列表。每次分享都必须包含 `shareId`。
`enabled`	启用商品目录	`true`	指定目录是否已启用。

数据：模块：商品

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

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

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

modules:
  # List of data product modules.
  products:
    # Unique identifier for the data product instance.
    - moduleId: sap_purchasing_organizational_structure
      # Path of the data product (namespaced).
      modulePath: cortex.sap.products.purchasing_organizational_structure
      # Map of module dependencies.
      dependencyBindings:
        sapModule: erp
      # Reference to the target dataset ID.
      dataTargetId: product_target
      # Whether the module is enabled.
      enabled: true
      # Whether this data product is synced to the Knowledge Catalog. Defaults to true.
      syncToKc: true

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

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

参数	含义	默认值	说明
`moduleId`	模块标识符	-	特定转换模块实例的唯一标识符。
`modulePath`	模块路径	-	定义了模块、业务逻辑或应用的模板的命名空间路径，格式为：{namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}，例如 `cortex.sap.products.purchasing_organizational_structure`（在 `src/data_modules/{namespace_dir}/{system_type}/products/{product_name}` 文件夹中定义）。
`dataTargetId`	目标链接	`product_target`	引用目标列表中的“id”，以将数据推送到该目标。
`dependencyBindings`	上游依赖项	`sapModule: erp`	指定用于满足模块依赖项的映射。例如，将 `sapModule` 映射到 `erp`。
`enabled`	模块启用	`true`	指定模块是否已启用。
`syncToKc`	Knowledge Catalog 同步	`true`	相应数据产品是否已同步到 Knowledge Catalog。
`tableSettings`	表设置	`src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml`	自定义表格设置配置文件的路径（相对于此配置文件）。推荐路径：相对于 `config/` 目录：'{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml' 默认路径：'../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/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-central1` 或 `europe-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_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml（例如，config/cortex/sap/foundations/sap/table_settings.yaml）
- 产品模块： namespace_dir/system_type/products/product_name/custom_table_settings.yaml（例如，config/cortex/sap/products/accounting_documents/table_settings.yaml）
默认回退：如果省略 tableSettings，框架会自动回退到：
- 基础模块： ../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
- 产品模块： ../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

配置样式

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

数据基础样式：基于列表的映射，用于定义源到目标架构关系、CDC（变更数据捕获）处理和 BigQuery 布局。请注意，数据基础表设置布局特定于源系统。
数据产品样式：基于地图的映射（字典），用于定义如何具体化（例如作为视图、表或增量表）和优化分析视图或表。

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

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

SAP ERP 的数据基础样式

在 SAP ERP 源系统的数据基础模块中，table_settings.yaml 文件的结构为 ecc、s4 和 common 键下的表项列表。每个项都会将原始源表映射到规范化的目标表，并配置其 BigQuery 设置。

YAML 语法示例

common:
  - source:
      tableName: raw_custom_bkpf
      sapTableName: bkpf
      isCdc: true
    target:
      tableName: bkpf # Optional: defaults to source tableName if omitted
      bigQueryLabels:
        - key: data_class
          value: transactional
        - key: line_of_business
          value: finance
      dataformTags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day
    deployAlways: false

参数引用

参数	类型	必填	默认值 / 示例	说明
`[].source`	`object`	是	`[]`	描述数据基础入站源系统（例如 `sap_raw`）中的表。请参阅来源设置。
`[].target`	`object`	是	`[]`	描述数据基础数据集（例如 `sap_data_foundation`）中的目标表。请参阅目标设置。
`ecc` \| `s4` \| `common`	`string`	否	`[]`	源系统版本或方言。
`[].deployAlways`	`boolean`	否	`false`	如果值为 `true`，则始终会部署和构建相应表，即使优化规则可能会跳过该表也是如此。另请参阅动态依赖项解析

来源设置

定义原始入站表的特征。

参数类型必填默认值 / 示例说明

tableName string 是 - BigQuery 中原始源表的名称（不区分大小写），因为该表是由连接器从源系统导入的。

sapTableName string 否 - 源系统元数据表（例如 `DD03L`）中定义的 SAP 表名称（不区分大小写）。如果定义了此参数，则会将其用作相应数据基础表的名称。

参数	类型	必填	默认值 / 示例	说明
`tableName`	`string`	是	`-`	BigQuery 中原始源表的名称（不区分大小写），因为该表是由连接器从源系统导入的。
`sapTableName`	`string`	否	`-`	源系统元数据表（例如 `DD03L`）中定义的 SAP 表名称（不区分大小写）。如果定义了此参数，则会将其用作相应数据基础表的名称。
`isCdc`	`boolean`	否	`true`	指示源表是否包含变更数据捕获 (CDC) 日志。 • `true`（默认）：框架会处理 CDC 日志（使用记录时间戳和操作标志）来重建最新的规范化状态。 • `false`：系统会将相应表作为完整快照进行处理。

isCdc

boolean

否

true

指示源表是否包含变更数据捕获 (CDC) 日志。

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

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

目标设置

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

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

数据产品样式

在数据产品模块中，table_settings.yaml 文件（ProductTableSettings 代码块）在 ecc、s4 和 common 根键下以字典（映射）的形式进行结构化。此字典的键表示目标分析表或视图名称（不区分大小写），每个值都是一个 Product TableItem (ProductTableItem) 配置块，用于定义具体化策略、表启用和性能优化。

YAML 语法示例

common:
  currency_conversion:
    materializationType: table
    bigQueryLabels:
      - key: data_class
        value: transactional
      - key: line_of_business
        value: finance
    dataformTags: [sap, dataproduct, common]
    enabled: true
    retentionDays: 365 # Custom parameter passed to Dataform context
s4:
  customers:
    materializationType: incremental
    bigQueryLabels:
      - key: data_class
        value: master
    dataformTags: [sap, dataproduct, masterdata]
    enabled: true
    clusterDetails:
      columns: [mandt, ktokd]
    partitionDetails:
      column: erdat
      partitionType: time
      timeGrain: day

参数引用

参数	类型	必填	默认值 / 示例	说明
`ecc` \| `s4` \| `common`	`map`	否	`{}`	目标分析型资产（表或视图）与其 `ProductTableItem` 配置描述符的映射。
`[table_name]`	`map`	否	`{}`	用于配置特定分析型资产的 Product Table Item 描述符架构块。
`[table_name].enabled`	`boolean`	否	`true`	控制在构建 Dataform 工作区时，分析表或视图 (`[table_name]`) 是否处于有效状态并包含在内。 • `true`（默认）：系统会处理表定义，使用 `table_config` 属性对其进行扩充，然后将其复制到 Dataform 输出目录。 • `false`：在 build 期间跳过表定义（`SapProductBuilder` 日志并省略它）。相应表或视图不会被复制或构建到 Dataform 中，从而在不删除源定义文件的情况下有效地将其从部署中排除。
`[table_name].materializationType`	`string`	否	`incremental`	如何在 BigQuery 中构建分析型资产。允许的值： `incremental`（默认）：仅处理自上次运行以来新增或更新的记录。建议用于大型事务性数据集，以节省费用。 `table`：在每次运行时从头开始完全重建表。 `view`：将资产部署为 BigQuery SQL 视图（虚拟表）。
`[table_name].dataformTags`	`array[string]`	否	`[sap, dataproduct]`	附加到 Dataform 中分析资产的元数据标记。这些是任意字符串，无需预先注册；它们可立即用于选择性流水线运行（例如，使用 `dataform run --tags ...`）。
`[table_name].bigQueryLabels`	`array[map]`	否	`-`	一个键值对列表，表示要应用于目标分析资产的 BigQuery 标签（例如，键：`data_class`，值：`master`）。
`[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`	如果 `partitionType` 为 `time` 或 `DATE`，则为必需。定义时间分区的粒度。允许的值： `hour`、`day`、`month`、`year`（不区分大小写）。
`rangeStart`	`integer`	否	`1`	如果 `partitionType` 为 `integer`，则必须提供此值。第一个分区的起始值（含边界值）。
`rangeEnd`	`integer`	否	`1000`	如果 `partitionType` 为 `integer`，则必须提供此值。最后一个分区的结束值（不含）。
`rangeInterval`	`integer`	否	`10`	如果 `partitionType` 为 `integer`，则必须提供此值。每个分区区间的宽度。

示例

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

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

此示例展示了如何配置一个基础层，其中包含聚簇和分区事务表（如 bseg 和 ekbe）以及标准数据表：

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

# ==============================================================================
# ECC-Specific Tables
# ==============================================================================
ecc:
  - source:
      tableName: faglflexa
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, ecc, finance, transactional, hourly]

# ==============================================================================
# Common Tables (ECC & S/4HANA)
# ==============================================================================
common:
  # Financial document header (partitioned by posting date)
  - source:
      tableName: bkpf
      isCdc: true
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [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:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [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:
      bigQueryLabels:
        - key: data_class
          value: master
      dataformTags: [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
    bigQueryLabels:
      - key: data_class
        value: transactional
    dataformTags: [sap, dataproduct, sales, transactional]
    clusterDetails:
      columns: [vkorg, vbeln]
    partitionDetails:
      column: audat
      partitionType: time
      timeGrain: day

  # Master data product - full table rebuild
  customers:
    materializationType: table
    bigQueryLabels:
      - key: data_class
        value: master
    dataformTags: [sap, dataproduct, masterdata]
    clusterDetails:
      columns: [mandt, ktokd]

  # Aggregated reporting view - virtual view
  sales_performance_summary:
    materializationType: view
    bigQueryLabels:
      - key: data_class
        value: transactional
    dataformTags: [sap, dataproduct, sales, reporting]

方法指南

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

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

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

将默认的 table_settings.default.yaml 配置复制到工作区配置目录（例如 config/cortex/sap/foundations/sap/custom_table_settings.yaml）。
在新文件中，根据需要添加自定义表格或移除 ecc、s4 或 common 键下的未使用的标准表格：

common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]

更新 config/config.yaml 以引用模块 tableSettings 属性下自定义表格设置的路径：

data:
  modules:
    foundations:
      - moduleId: erp
        modulePath: cortex.sap.foundations.sap
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
        tableSettings: 'cortex/sap/foundations/sap/custom_table_settings.yaml'

如需使用注解（表和列说明）来丰富附加表的表架构，请在您使用的数据基础模块的命名空间中创建一个注解文件。在此示例中，根据 modulePath: cortex.sap.foundations.sap，用于存储注解文件 custom_table_name.yaml 的路径为 src/data_modules/cortex/sap/foundations/sap/annotations。如需了解注解文件的格式，请参阅数据基础的可扩展性指南。

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

部署同一模块类型的两个或更多个单独的流水线实例（例如，支持多个 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.foundations 列表下定义模块的多个实例。为每个实例提供唯一的 moduleId、自己的目标数据集 ID，以及可选的 tableSettings 配置：

data:
  modules:
    foundations:
      # Core SAP ERP foundation module instance
      - moduleId: erp_core
        modulePath: cortex.sap.foundations.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_core
        # If omitted, defaults to "../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml"
        # tableSettings: "../src/data_modules/cortex/sap/foundations/sap/table_settings.default.yaml"
      # Custom tables pipeline instance
      - moduleId: erp_custom
        modulePath: cortex.sap.foundations.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_custom
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
        tableSettings: "cortex/sap/foundations/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:
      dataformTags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day

如需使用注解（表和列说明）来丰富附加表的表架构，请在您使用的数据基础模块的命名空间中创建一个注解文件。在此示例中，根据 modulePath: cortex.sap.foundations.sap，用于存储注解文件 custom_table_name.yaml 的路径为 src/data_modules/cortex/sap/foundations/sap/annotations。如需了解注解文件的格式，请参阅数据基础的可扩展性指南。
运行部署脚本 (uv run cortex-build-and-deploy) 以应用更改，然后按照部署后步骤中所述执行 Dataform 操作。

部署配置

配置文件：config/config.yaml

构建环境

“数据”部分概览

数据：BigQuery 位置

数据：Cortex 命名空间

数据：BigQuery 源数据集和目标数据集

数据：模块

数据：模块：基础知识

数据：模块：目录

数据：模块：商品

部署环境

配置文件：table_settings.yaml

动态依赖项解析

配置路径

配置样式

SAP ERP 的数据基础样式

YAML 语法示例

参数引用

来源设置

目标设置

数据产品样式

YAML 语法示例

参数引用

高级 BigQuery 配置

聚类详细信息

参数引用

分区详细信息

参数引用

示例

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

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

方法指南

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

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

配置文件：`config/config.yaml`

配置文件：`table_settings.yaml`