커스텀 네임스페이스 설정

맞춤 네임스페이스는 데이터 파운데이션 및 분석 데이터 제품 모듈을 패키징하고 격리하는 논리적 환경 역할을 합니다. 전용 커스텀 네임스페이스 내에서 실행하면 구성 및 배포 옵션을 독립적으로 관리하여 환경을 격리할 수 있습니다. 이 분리의 주요 이점은 커스텀 모듈을 재정의하거나 손상시킬 위험 없이 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/ 폴더에 배치할 수 있습니다.
  • 빌더 - 모듈 소스 코드를 Dataform 아티팩트로 컴파일할 수 있는 맞춤 생성기 클래스입니다. src/data_modules/custom_namespace_path/common/에 배치할 수 있습니다.

빌더 이해 및 참조

빌더는 모듈 소스 파일을 실제 Dataform 출력으로 컴파일하는 Python 생성기 클래스입니다. Google Cloud Cortex Framework는 유연한 3계층 빌더 해결 시퀀스를 사용하여 모듈을 컴파일합니다.

Google Cloud Cortex Framework 확장성 빌더 해결 시퀀스

그림 1. Cortex Framework 확장성 빌더 해결 시퀀스

Tier 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

Tier 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/'

다음 단계인 데이터 파운데이션 모듈 생성 및 데이터 제품 모듈 생성에서는 네임스페이스에 데이터 모듈을 추가하는 방법을 알아봅니다.