배포 구성

이 페이지에서는 다음 영역에서 Cortex Framework의 배포 구성 옵션을 설명합니다.

이 페이지에서는 일반적인 배포 사용 사례 및 시나리오에 대한 단계별 안내가 포함된 방법 가이드도 제공합니다.

구성 파일: config/config.yaml

config/config.yaml 파일은 일반적으로 config/config.yaml.example 템플릿에서 초기화되며 Cortex Framework 배포의 기본 구성으로 사용됩니다. 구성에는 다음과 같은 구조적 블록이 있습니다.

  1. 빌드 환경 (buildEnvironment): 빌드 조정 레이어를 관리하며, 중간 메타데이터 계산, 데이터베이스 검증, 스키마 조회가 청구되고 실행되는 중앙 Google Cloud 프로젝트를 지정합니다.
  2. 데이터 (data): 논리적 데이터 아키텍처를 관리합니다. 이 블록은 데이터 세트 위치, 네임스페이스 경계, 원시 수집 소스의 연결 세부정보, 대상 데이터 세트를 구성하고 데이터 모듈 인스턴스 (foundations, catalogs, products)를 등록합니다.
  3. 배포 (deployment): 실제 타겟 시스템 배포를 구성합니다. 컴파일된 SQLX/JS 변환 파이프라인이 배포되는 Dataform 저장소 세부정보 (프로젝트 ID, 위치, 저장소 이름, 개발 작업공간)를 지정합니다.

다음 섹션에서는 각 블록을 자세히 설명합니다.

빌드 환경

빌드 환경 프로젝트는 DD03L를 읽는 BigQuery 작업과 같은 빌드 작업에 대해 요금이 청구되는 프로젝트입니다.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

다음 표에서는 빌드 환경 매개변수를 설명합니다.

매개변수 의미 기본값 설명
buildEnvironment.buildProjectId 빌드 프로젝트 ID YOUR_BUILD_PROJECT_ID Google Cloud 빌드 작업이 실행되는 프로젝트 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'를 참조합니다.
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'

데이터: 모듈: 카탈로그

외부 레이크하우스 카탈로그를 사용하면 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}입니다. 예를 들어 src/data_modules/{namespace_dir}/{system_type}/products/{product_name} 폴더에 정의된 cortex.sap.products.purchasing_organizational_structure입니다.
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에서 각 모듈 (기반 또는 제품)에는 tableSettings 속성을 사용하여 배포 구성 파일: config/config.yaml에 특정 테이블 설정 파일을 할당할 수 있습니다.

구성 경로

  • 맞춤 설정 (권장): 표 동작을 맞춤설정하려면 기본 파일을 구성 디렉터리에 복사하고 수정하고 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에는 두 가지 스키마 스타일이 있습니다.

  1. 데이터 파운데이션 스타일: 소스-타겟 스키마 관계, CDC (변경 데이터 캡처) 처리, BigQuery 레이아웃을 정의하는 목록 기반 매핑입니다. 데이터 파운데이션 테이블 설정 레이아웃은 소스 시스템에 따라 다릅니다.

  2. 데이터 제품 스타일: 분석 뷰 또는 테이블이 구체화 (예: 뷰, 테이블 또는 증분 테이블)되고 최적화되는 방식을 정의하는 맵 기반 매핑 (사전)입니다.

두 스타일 모두 소스 시스템 버전별로 구성을 분리하는 세 개의 루트 수준 섹션을 지원합니다 (주로 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 아니요 - 소스 시스템 메타데이터 테이블에 정의된 SAP 테이블 이름 (대소문자 구분 안 함)(예: `DD03L`). 정의된 경우 이 매개변수는 해당 데이터 파운데이션 테이블의 이름으로 사용됩니다.
isCdc boolean 아니요 true 소스 테이블에 변경 데이터 캡처 (CDC) 로그가 포함되어 있는지 나타냅니다.

• true(기본값): 프레임워크는 레코드 타임스탬프와 작업 플래그를 사용하여 CDC 로그를 처리하여 최신 준수 상태를 재구성합니다.

• false: 테이블이 전체 스냅샷으로 처리됩니다.
타겟 설정

타겟 데이터 세트에서 출력 준수 테이블 레이아웃을 정의합니다.

매개변수 유형 필수 기본값 / 예 설명
tableName string 아니요 *(소스와 동일)* 만들려는 대상 준수 테이블의 이름입니다. 생략하면 프레임워크는 기본적으로 tableName 소스를 사용합니다.
dataformTags array[string] 아니요 [sap, finance] Dataform에서 적합한 작업에 연결된 메타데이터 태그 목록입니다. 이는 임의의 문자열이며 다른 구성에서 사전 등록하거나 정의할 필요가 없습니다. 파이프라인 실행을 필터링하는 데 즉시 사용할 수 있습니다 (예: dataform run --tags ... 사용).
bigQueryLabels array[map] 아니요 - 대상 테이블에 적용할 BigQuery 라벨을 나타내는 키-값 쌍 목록입니다 (예: key: data_class, value: 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 아니요 {} 특정 분석 애셋을 구성하는 제품 표 항목 설명자 스키마 블록
[table_name].enabled boolean 아니요 true Dataform 작업공간을 빌드할 때 분석 테이블 또는 뷰 ([table_name])가 활성 상태이고 포함되는지 여부를 제어합니다.

• true (기본값): 테이블 정의가 처리되고 table_config 속성으로 보강되어 Dataform 출력 디렉터리에 복사됩니다.

• false: 빌드 중에 테이블 정의가 건너뛰어집니다 (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 라벨을 나타내는 키-값 쌍 목록입니다 (예: key: data_class, value: 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개의 열 이름이 포함된 정렬된 목록입니다.

제약 조건: 열은 영숫자여야 하며 밑줄만 포함해야 합니다. 목록의 열 순서에 따라 정렬 계층 구조가 결정됩니다.

파티셔닝 세부정보

파티셔닝은 날짜, 타임스탬프 또는 정수 열의 값을 기준으로 큰 테이블을 더 작은 물리적 세그먼트로 나눕니다. 이렇게 하면 쿼리에서 특정 범위의 일, 월 또는 ID만 요청할 때 BigQuery가 전체 테이블을 스캔하지 않습니다.

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은 증분으로 설정하고 customers과 같은 비트랜잭션 데이터 테이블은 표준 테이블로 빌드합니다.

# 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]
  • 모듈의 tableSettings 속성 아래에 있는 맞춤 테이블 설정의 경로를 참조하도록 config/config.yaml를 업데이트합니다.
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 파일을 만듭니다. 예:
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 작업을 실행합니다.