设置自定义命名空间

自定义命名空间充当逻辑环境，用于打包和隔离数据基础和分析型数据产品模块。在专用自定义命名空间内运行可让您独立管理配置和部署选项，从而为您的环境提供隔离。这种分离的主要优势在于，您可以从 Google Cloud Cortex Framework 中的 cortex 命名空间无缝提取未来的更新和增强功能，而不会有覆盖或损坏自定义模块的风险。我们强烈建议您在专用命名空间内创建自定义模块。

自定义命名空间文件夹结构

Cortex Framework 命名空间文件夹用于打包和隔离自定义模块工件。自定义命名空间的文件夹结构在下表中定义：

目录路径 用途和说明 典型的子文件夹结构
config/ Cortex 部署配置 （必需）
创建新命名空间需要在 config.yaml 中进行设置。 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ 数据基础模块 （可选）
原始数据到基础数据集的转换。 
-
src/data_modules/custom_namespace_path/data_product/ 数据产品定义 （可选）
包含业务逻辑和分析模型。每个产品都以子目录（例如 your_product_name）分隔，并包含以下内容：
  • Readme：模块的文档
  • manifest.yaml：声明构建器类型、依赖项和配置。
  • annotations/：列级和字段级说明。
  • definitions/：Dataform SQLX 或 JS 源文件。
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ JavaScript 帮助程序 （可选）
放置在此处的任何 JavaScript 文件都会自动打包，并在编译期间在命名空间路径（例如 includes/custom_namespace/）下提供给 Dataform 模型。 
-
src/data_modules/custom_namespace_path/common/ 命名空间共享工具 （可选）
命名空间级自定义构建器、部署器和其他工具。 
-

自定义命名空间配置

您可以通过扩展 config.yaml 文件的相应部分、在 src/data_modules/ 下创建新目录并添加新模块代码资产，来定义新命名空间：custom_namespace。

如需让 Google Cloud Cortex Framework 编译器识别您的自定义命名空间和模块，您必须在全局配置文件（例如 config/config.yaml）中注册它们。

步骤 A：注册命名空间

在 data.namespaces 块下，添加您的命名空间元数据：

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name:  custom_namespace    # <-- Name of custom namespace
      path:  custom_namespace_path/  # <-- Folder name that is used for custom namespace, points to subdirectory of 'src/data_modules/'

步骤 B：配置自定义模块

在 data.modules.foundation 或 data.modules.product 下注册您的自定义模块。对于 type 字段，请使用以英文句点分隔的格式 custom_namespace.module_type：

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_foundation_module_id
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        tableSettings: "config/custom_namespace_path/data_foundation/sap/table_settings.yaml"

    product:
      - moduleId: custom_namespace_data_product_id
        type: custom_namespace.data_product_id  # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: erp_ecc            # References an existing foundation moduleId
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_id/table_settings.yaml"

自定义命名空间共享代码

自定义命名空间支持在其模块之间共享代码工件。支持的工件类型包括：

  • includes - 包含将提供给 Dataform 工件的任何 JavaScript 帮助程序。它们可以放置在以下文件夹中：src/data_modules/custom_namespace_path/includes/。
  • builders - 任何可将模块源代码编译为 Dataform 工件的自定义生成器类。它们可以放置在 src/data_modules/custom_namespace_path/common/ 中。

了解和引用构建器

构建器是 Python 生成器类，可将模块源文件编译为物理 Dataform 输出。Google Cloud Cortex Framework 使用灵活的三层构建器解析序列 编译模块：

Google Cloud Cortex Framework 可扩展性构建器解析序列

图 1. Cortex Framework 可扩展性构建器解析序列。

第 1 层：全局回退构建器

该框架包含位于 src/common/builders/ 中的高度可靠的构建器。这些构建器是全局注册的，可供任何 自定义命名空间使用。

例如，如需将标准 SAP 数据产品构建器用于自定义产品，请在 manifest.yaml 中引用 sap_product：

# src/data_modules/custom_namespace_path/data_product/data_product_id/manifest.yaml
type: data_product_id
builder: sap_product     # Automatically resolves to the global SapProductBuilder fallback
dependencies:
  sapModule:
    type: sap
    supportedVersions:
      - ecc
      - s4

第 2 层：命名空间级构建器

如果自定义命名空间内的模块需要专用编译器，您可以为该命名空间注册自定义构建器。

  1. 在 src/data_modules/custom_namespace_path/common/builders/my_builder.py 下创建一个构建器文件。

  2. 使用 @builder_registry.register("my_builder") 修饰构建器类：

   from common.builders.base import ProductBuilder
   from common.registry import builder_registry

   @builder_registry.register("my_builder")
   class MyCustomProductBuilder(ProductBuilder):
       # Implement build logic here...
  1. 使用 builder: my_builder 在产品的 manifest.yaml 中引用它。

第 3 层：单个产品级构建器

对于高度独特的流水线，您可以定义一个构建器，其范围 仅 限为单个数据产品。

  1. 只需在数据产品文件夹（例如 src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py）内直接创建一个名为 builder.py 的文件即可。

  2. 在其中定义 BaseBuilder 或 ProductBuilder 的子类：

   from common.builders.base import ProductBuilder

   class UniqueSalesPerformanceBuilder(ProductBuilder):
       # Implement unique build logic here...
  1. 编译器将自动动态导入并执行此类，而无需任何注册或修饰器。

自定义命名空间示例

在 config/config.yaml 文件中，在 data.namespaces 下添加以下块：

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name: sap_bookingdatamodel # <-- Name of custom namespace: sap_bookingdatamodel
      path: sap_bookingdatamodel/  # <-- Folder name that is used for custom namespace:sap_bookingdatamodel, points to subdirectory of 'src/data_modules/'

在接下来的步骤中：创建数据基础模块和创建数据产品模块，您将了解如何向命名空间添加数据模块。