部署配置
本文档介绍了 Cortex Framework 在以下方面的部署配置选项:
- 部署配置 (
config/config.yaml):定义全局变量、构建环境和模块映射(数据基础和数据产品目标)。 - 表配置 (
table_settings.yaml):模块特定的性能和架构规范,概述了如何在 BigQuery 中编译和调整基本表。
本指南还提供了操作指南,其中包含针对常见部署用例和场景的分步说明。
配置文件: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 数据集位置(例如 US、us-central1 或 europe-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-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/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 有两种不同的架构样式,具体取决于模块的类别:
- 数据基础样式:基于列表的映射,用于定义源到目标的架构关系、CDC(变更数据捕获)处理和 BigQuery 布局。
- 数据产品样式:基于地图的映射(字典),用于定义如何具体化(例如作为视图、表或增量表)和优化分析视图或表。
这两种样式都支持三个根级部分,用于按源系统版本(主要用于 SAP Data Foundation 和依赖于 SAP 的产品)分隔配置:
ecc:仅在部署 SAP ECC 源系统时应用的设置。s4:仅在部署 SAP S/4HANA 源系统时应用。common:无论 SAP 版本如何,都会应用设置(用于一致或通用设置)。
数据基础样式
在 Data Foundation 模块中,table_settings.yaml 文件的结构为 ecc、s4 和 common 键下的表项列表。每个项都会将原始源表映射到一致的目标表,并配置其 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) 日志。
• • |
目标设置
定义目标数据集中的输出一致化表布局。
| 参数 | 类型 | 必需 | 默认 / 示例 | 说明 |
|---|---|---|---|---|
tableName |
string |
否 | *(与来源相同)* | 要创建的目标一致性表的名称。如果省略,框架会默认使用来源 tableName。 |
tags |
array[string] |
否 | [sap, finance] |
附加到 Dataform 中已规范化操作的元数据标记列表。这些是任意字符串,无需预先注册或在其他配置中定义;它们可立即用于过滤流水线执行(例如,使用 dataform run --tags ...)。 |
clusterDetails |
map |
否 | — | 可选。BigQuery 聚簇配置。请参阅聚类详细信息。 |
partitionDetails |
map |
否 | — | 可选。BigQuery 分区配置。请参阅分区详细信息。 |
数据产品样式
在数据产品模块中,table_settings.yaml 文件在 ecc、s4 和 common 键下以字典(映射)的形式结构化。字典的键表示分析表或视图名称,值定义了它们的具体化和性能设置。
YAML 语法示例
s4:
customers:
materializationType: incremental
tags: [sap, dataproduct, masterdata]
clusterDetails:
columns: [mandt, ktokd]
参数引用
| 参数 | 类型 | 必需 | 默认 / 示例 | 说明 |
|---|---|---|---|---|
ecc | s4 | common |
map |
否 | {} |
目标分析型资产(表或视图)与其配置的映射。 |
[table_name].materializationType |
string |
否 | incremental |
如何在 BigQuery 中构建分析型资产。
允许的值:
|
[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 |
划分策略。 允许的值:
|
timeGrain |
string |
否 | day |
如果 partitionType 为 time 或 DATE,则为必需。定义时间分区的粒度。
允许的值: |
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:
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)。 - 在新文件中,根据需要添加自定义表格或移除
ecc、s4或common键下的未使用的标准表格:
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 操作。