Konfigurasi deployment

Halaman ini menjelaskan opsi konfigurasi deployment untuk Cortex Framework di seluruh area berikut:

• Konfigurasi deployment (config/config.yaml): Menentukan variabel global, lingkungan build, dan pemetaan modul (target produk data dan fondasi data).
• Konfigurasi tabel (table_settings.yaml): Spesifikasi performa dan skema khusus modul, yang menguraikan cara tabel dasar dikompilasi dan disesuaikan di BigQuery.

Halaman ini juga menyediakan Panduan cara dengan petunjuk langkah demi langkah untuk kasus penggunaan dan skenario deployment umum.

File konfigurasi: config/config.yaml

File config/config.yaml — biasanya diinisialisasi dari template config/config.yaml.example — berfungsi sebagai konfigurasi utama untuk deployment Cortex Framework. Konfigurasi dibagi menjadi blok struktural berikut:

1. Lingkungan build (buildEnvironment): Mengatur lapisan orkestrasi build, yang menentukan project Google Cloud pusat tempat perhitungan metadata perantara, validasi database, dan pencarian skema ditagih dan dieksekusi.
2. Data (data): Mengatur arsitektur data logis. Blok ini mengonfigurasi lokasi set data, batas namespace, detail koneksi untuk sumber penyerapan mentah, set data tujuan, dan mendaftarkan instance modul data (foundations, catalogs, dan products).
3. Deployment (deployment): Mengonfigurasi deployment sistem target fisik. Bagian ini menentukan detail repositori Dataform (project ID, lokasi, nama repositori, dan ruang kerja pengembangan) tempat pipeline transformasi SQLX/JS yang dikompilasi di-deploy.

Bagian berikut memberikan perincian mendetail dari setiap blok.

Lingkungan build

Project lingkungan build adalah project yang ditagih untuk tindakan build, seperti tugas BigQuery yang membaca DD03L.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

Tabel berikut menjelaskan parameter lingkungan build.

Parameter	Arti	Nilai default	Deskripsi
buildEnvironment.buildProjectId	Build project ID	YOUR_BUILD_PROJECT_ID	Google Cloud Project ID tempat operasi build dijalankan.

Ringkasan bagian data

Bagian data: dari file konfigurasi menentukan sumber data, target, dan modul spesifik untuk fondasi data dan produk data Anda. Struktur umumnya adalah sebagai berikut:

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:
    - ...

Data: Lokasi BigQuery

Menentukan lokasi set data sumber dan target BigQuery.

Parameter	Arti	Nilai default	Deskripsi
data.bigQueryLocation	Lokasi BigQuery	US	Lokasi set data BigQuery (misalnya, US, us-central1, atau europe-west1).

Data: Namespace Cortex

Menentukan namespace Cortex Framework.

Parameter	Arti	Nilai default	Deskripsi
data.namespaces.name	Nama namespace	-	Nama namespace Cortex Framework. Misalnya, cortex.
data.namespaces.path	Jalur namespace	-	Jalur namespace Cortex Framework untuk subdirektori yang digunakan dalam folder src dan config. Misalnya, cortex.

Data: Sumber BigQuery dan set data target

Daftar set data menentukan titik koneksi data mentah masuk dan lokasi penyimpanan keluar untuk framework. Setiap set data mendaftarkan ID unik yang dipetakan ke project Google Cloud dan set data BigQuery tertentu.

Kumpulan data dirujuk dari modul menggunakan ID uniknya.

# 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

Tabel berikut menjelaskan parameter pemetaan set data.

Parameter	Arti	Nilai default	Deskripsi
data.datasets.id	ID set data	-	Menentukan ID unik untuk set data (misalnya, sap_raw atau sap_foundation).
data.datasets.projectId	ID Project	-	Merujuk ke Google Cloud Project ID yang menghosting set data.
data.datasets.datasetId	ID Set Data BigQuery	-	Merujuk pada nama set data BigQuery yang sebenarnya.

Data: Modul

Modul menentukan struktur dan komponen pipeline data Dataform.

Data: Modul: Dasar-Dasar

Bagian ini mengonfigurasi modul lapisan fondasi data yang memproses data dari lapisan mentah menjadi representasi data sumber yang distandardisasi dan terbaru. Jika sumber menyediakan tampilan langsung pada data terbaru, atau transformasi tersebut dilakukan oleh konektor sistem sumber, modul dapat dikonfigurasi sebagai sumber fondasi data eksternal.

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"

Tabel berikut menjelaskan parameter modul fondasi data untuk konfigurasi modules.foundations.

Parameter	Arti	Nilai default	Deskripsi
moduleId	ID Modul	erp	ID unik untuk instance modul transformasi fondasi data tertentu.
modulePath	Jalur Modul	cortex.sap.foundations.sap	Mendefinisikan jalur namespace ke modul, logika bisnis, atau template yang diterapkan. Format: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap} (misalnya, cortex.sap.foundations.sap).
dataSourceId	Link Sumber	sap_raw	Mereferensikan 'id' dari daftar data.datasets untuk menarik data.
dataTargetId	Link Target	sap_foundation	Mereferensikan 'id' dari daftar data.datasets untuk mengirim data ke.
moduleSettings.sapVersion	Versi Sistem SAP	ecc	Hanya berlaku untuk sumber data SAP. Menentukan logika khusus sumber untuk sistem ecc (ECC) atau s4 (S/4HANA).
moduleSettings.mandt	Klien SAP (Mandant)	100	Hanya berlaku untuk sumber data SAP. ID klien SAP 3 digit yang digunakan untuk memfilter baris data.
enabled	Pengaktifan modul	true	Menentukan apakah modul diaktifkan.
external	Fondasi eksternal	false	Menentukan apakah fondasinya eksternal (tidak membuat set data target).
tableSettings	Setelan tabel	src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml	Jalur ke file konfigurasi Setelan tabel kustom, relatif terhadap file konfigurasi ini. Jalur yang direkomendasikan: relatif terhadap direktori `config/`: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml' Jalur default: '../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'

Data: Modul: Katalog

Katalog lakehouse eksternal memungkinkan Cortex Framework menyerap tabel eksternal dari katalog dan berbagi BigLake Delta Sharing tanpa manifes fisik.

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

Tabel berikut menjelaskan parameter konfigurasi katalog eksternal.

Parameter	Arti	Nilai default	Deskripsi
id	ID Katalog	-	ID unik untuk instance modul katalog eksternal tertentu.
type	Jenis Katalog	lakehouse_delta_share	Jenis katalog. Mendukung lakehouse_delta_share.
bindsNamespaces	Namespace yang Terikat	-	Daftar awalan namespace logis yang terikat oleh katalog ini (misalnya, [sap_bdc]).
connectionSettings.catalogId	ID Katalog Fisik	-	ID katalog fisik. Biasanya sama dengan ID modul.
connectionSettings.projectId	ID Project	-	Google Cloud Project ID tempat koneksi katalog dikelola.
connectionSettings.location	Lokasi	-	Lokasi wilayah geografis untuk katalog.
connectionSettings.shares	Berbagi	-	Daftar berbagi Delta Sharing yang akan diimpor. Setiap pembagian harus berisi shareId.
enabled	Pengaktifan Katalog	true	Menentukan apakah katalog diaktifkan.

Data: Modul: Produk

Modul produk data menentukan agregasi, penghitungan, dan gabungan yang diperlukan untuk mengubah data mentah menjadi insight yang memenuhi kasus penggunaan bisnis tertentu.

Konfigurasi produk data memungkinkan penetapan ID unik, definisi dependensi, serta referensi modul fondasi data dan set data target tempat hasil akan disimpan.

Konfigurasi mendetail dari produk data tertentu ditentukan dalam file yang dirujuk oleh kunci: 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"

Tabel berikut menjelaskan parameter modul produk data untuk konfigurasi modules.products.

Parameter	Arti	Nilai default	Deskripsi
moduleId	ID Modul	-	ID unik untuk instance modul transformasi tertentu.
modulePath	Jalur Modul	-	Mendefinisikan jalur dengan namespace ke modul, logika bisnis, atau template yang diterapkan, format: {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}, misalnya, cortex.sap.products.purchasing_organizational_structure, yang ditentukan di folder src/data_modules/{namespace_dir}/{system_type}/products/{product_name}.
dataTargetId	Link Target	product_target	Merujuk 'id' dari daftar target untuk mengirim data ke.
dependencyBindings	Dependensi Upstream	sapModule: erp	Menentukan pemetaan untuk memenuhi dependensi modul. Misalnya, memetakan sapModule ke erp.
enabled	Pengaktifan modul	true	Menentukan apakah modul diaktifkan.
syncToKc	Sinkronisasi Knowledge Catalog	true	Apakah produk data ini disinkronkan ke Knowledge Catalog.
tableSettings	Setelan tabel	src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml	Jalur ke file konfigurasi Setelan tabel kustom, relatif terhadap file konfigurasi ini. Recommended path: relative to `config/` directory: '{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml' Default path: '../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml'

Lingkungan deployment

Cortex Framework menggunakan Dataform untuk mengatur transformasi SQL dalam BigQuery. Blok deployment: menentukan konfigurasi Dataform, yang bertanggung jawab atas eksekusi pipeline data, termasuk project repositori, lokasi, nama repositori, dan nama ruang kerja Dataform.

deployment:
  targets:
    - type: dataform
      enabled: true
      targetSettings:
        repositoryProjectId: YOUR_REPO_PROJECT_ID
        repositoryRegion: us-central1
        repositoryName: cortex-repository
        workspaceName: dev
        # serviceAccount: "[e-mail]"

Tabel berikut menjelaskan parameter lokasi target deployment (deployment.targets:).

Parameter	Arti	Nilai Default	Deskripsi
type	Jenis deployment	dataform	Jenis target deployment.
enabled	Diaktifkan/ Dinonaktifkan	true	Menentukan apakah target deployment tertentu diaktifkan atau dinonaktifkan.
targetSettings.repositoryProjectId	Project ID repositori	YOUR_REPO_PROJECT_ID	Google Cloud Project ID tempat repositori Dataform dikelola.
targetSettings.repositoryRegion	Region repositori	us-central1	Google Cloud region untuk repositori Dataform (misalnya, us-central1 atau europe-west1).
targetSettings.repositoryName	Nama repositori	cortex-repository	Nama spesifik repositori Dataform.
targetSettings.workspaceName	Nama Workspace	dev	Ruang kerja Dataform tertentu yang digunakan untuk siklus deployment.
targetSettings.serviceAccount	Email akun layanan	-	Email akun layanan default untuk eksekusi repositori Dataform.

---

File konfigurasi: table_settings.yaml

Panduan ini menjelaskan cara menggunakan file table_settings.yaml untuk mengonfigurasi tabel produk data dan fondasi data di Google Cloud Cortex Framework.

File table_settings.yaml khusus modul data mengontrol cara tabel sumber mentah disesuaikan dan cara model data analitis diwujudkan dalam BigQuery. Dengan menggunakan file ini, Anda dapat mengonfigurasi tag, strategi materialisasi, dan fitur performa BigQuery lanjutan seperti partisi atau pengelompokan.

Resolusi dependensi dinamis

Secara default, Cortex Framework mengoptimalkan jejak deployment dan waktu eksekusi hanya dengan men-deploy dan mengompilasi tabel dasar yang diperlukan sebagai dependensi produk data yang diaktifkan. Jika tabel yang dikonfigurasi di table_settings.yaml tidak memiliki produk data hilir aktif yang bergantung padanya, tabel tersebut akan dikecualikan dari deployment.

Untuk mengganti pengoptimalan ini dan memaksa deployment tabel dasar, Anda dapat menyetel atribut deployAlways ke true (lihat Referensi parameter gaya fondasi data).

Di Google Cloud Cortex Framework, setiap modul (dasar atau produk) dapat diberi file setelan tabel tertentu dalam file konfigurasi deployment: config/config.yaml menggunakan properti tableSettings.

Jalur konfigurasi

• Setelan kustom (Direkomendasikan): Untuk menyesuaikan perilaku tabel, salin file default ke direktori konfigurasi Anda, ubah, dan rujuk jalur di config/config.yaml. Jalur yang direkomendasikan untuk digunakan (relatif terhadap direktori config/), adalah:
  • Modul dasar: namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml (misalnya, config/cortex/sap/foundations/sap/table_settings.yaml)
  • Modul produk: namespace_dir/system_type/products/product_name/custom_table_settings.yaml (misalnya, config/cortex/sap/products/accounting_documents/table_settings.yaml)
• Penggantian default: Jika tableSettings tidak ada, framework akan otomatis kembali ke:
  • Modul dasar: ../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
  • Modul produk: ../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

---

Gaya konfigurasi

Ada dua gaya skema yang berbeda untuk table_settings.yaml, bergantung pada kategori modul:

1. Gaya Data Foundation: Pemetaan berbasis daftar yang menentukan hubungan skema sumber ke target, penanganan CDC (Change Data Capture), dan tata letak BigQuery. Perhatikan bahwa tata letak setelan tabel fondasi data khusus untuk sistem sumber.

2. Gaya Produk Data: Pemetaan berbasis peta (kamus) yang menentukan cara tampilan atau tabel analitik diwujudkan (misalnya, sebagai tampilan, tabel, atau tabel inkremental) dan dioptimalkan.

Kedua gaya mendukung tiga bagian tingkat root untuk memisahkan konfigurasi menurut versi sistem sumber (terutama digunakan untuk SAP Data Foundation dan produk yang bergantung pada SAP):

• ecc: Setelan hanya diterapkan saat men-deploy sistem sumber SAP ECC.
• s4: Setelan hanya diterapkan saat men-deploy sistem sumber SAP S/4HANA.
• common: Setelan diterapkan terlepas dari versi SAP (digunakan untuk setelan yang disesuaikan atau universal).

---

Gaya fondasi data untuk SAP ERP

Dalam modul fondasi data untuk sistem sumber SAP ERP, file table_settings.yaml disusun sebagai daftar item tabel di bawah kunci ecc, s4, dan common. Setiap item memetakan tabel sumber mentah ke tabel target yang disesuaikan dan mengonfigurasi setelan BigQuery-nya.

Contoh sintaksis 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

Referensi parameter

Parameter	Jenis	Wajib	Default / Contoh	Deskripsi
[].source	object	Ya	[]	Mendeskripsikan tabel di sistem sumber masuk fondasi data (misalnya, `sap_raw`). Lihat setelan sumber.
[].target	object	Ya	[]	Mendeskripsikan tabel target dalam set data fondasi data (misalnya, `sap_data_foundation`). Lihat setelan target.
ecc | s4 | common	string	Tidak	[]	Versi atau dialek sistem sumber.
[].deployAlways	boolean	Tidak	false	Jika true, tabel akan selalu di-deploy dan dibuat, meskipun aturan pengoptimalan mungkin akan melewatinya. Lihat juga Penyelesaian dependensi dinamis

Setelan sumber

Menentukan karakteristik tabel masuk mentah.

Parameter	Jenis	Wajib	Default / Contoh	Deskripsi
tableName	string	Ya	-	Nama tabel sumber mentah di BigQuery (tidak peka huruf besar/kecil) saat diimpor oleh konektor dari sistem sumber .
sapTableName	string	Tidak	-	Nama tabel SAP (tidak peka huruf besar/kecil) sebagaimana ditentukan dalam tabel metadata sistem sumber (misalnya, `DD03L`). Jika ditentukan, parameter ini digunakan sebagai nama untuk tabel fondasi data yang sesuai.
isCdc	boolean	Tidak	true	Menunjukkan apakah tabel sumber berisi log Pengambilan Data Perubahan (CDC). • true (default): Framework memproses log CDC (menggunakan stempel waktu data dan flag operasi) untuk merekonstruksi status terbaru yang sesuai. • false: Tabel diproses sebagai snapshot penuh.

Setelan target

Menentukan tata letak tabel yang disesuaikan output dalam set data target.

Parameter	Jenis	Wajib	Default / Contoh	Deskripsi
tableName	string	Tidak	*(Sama seperti sumber)*	Nama tabel yang disesuaikan target yang akan dibuat. Jika tidak ditentukan, framework akan menggunakan tableName sumber secara default.
dataformTags	array[string]	Tidak	[sap, finance]	Daftar tag metadata yang dilampirkan ke tindakan yang disesuaikan di Dataform. String ini bersifat arbitrer dan tidak perlu didaftarkan atau ditentukan sebelumnya dalam konfigurasi lain; string ini dapat langsung digunakan untuk memfilter eksekusi pipeline (misalnya, menggunakan dataform run --tags ...).
bigQueryLabels	array[map]	Tidak	-	Daftar pasangan kunci-nilai yang merepresentasikan label BigQuery untuk diterapkan ke tabel target (misalnya, key: data_class, value: transactional).
clusterDetails	map	Tidak	—	Opsional. Konfigurasi pengelompokan BigQuery. Lihat Detail pengelompokan.
partitionDetails	map	Tidak	—	Opsional. Konfigurasi pembuatan partisi BigQuery. Lihat Detail partisi.

---

Gaya produk data

Dalam modul produk data, file table_settings.yaml (blok ProductTableSettings) disusun sebagai kamus (peta) di bawah kunci root ecc, s4, dan common. Kunci kamus ini merepresentasikan nama tabel atau tampilan analitik target (tidak peka huruf besar/kecil), dan setiap nilai adalah blok konfigurasi Product TableItem (ProductTableItem) yang menentukan strategi materialisasi, pengaktifan tabel, dan pengoptimalan performa.

Contoh sintaksis 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

Referensi parameter

Parameter	Jenis	Wajib	Default / Contoh	Deskripsi
ecc | s4 | common	map	Tidak	{}	Peta aset analisis target (tabel atau tampilan) ke deskriptor konfigurasi ProductTableItem.
[table_name]	map	Tidak	{}	Blok skema deskriptor Item Tabel Produk yang mengonfigurasi aset analitik tertentu.
[table_name].enabled	boolean	Tidak	true	Mengontrol apakah tabel atau tampilan analitis ([table_name]) aktif dan disertakan saat membangun ruang kerja Dataform. • true (default): Definisi tabel diproses, dilengkapi dengan properti table_config, dan disalin ke direktori output Dataform. • false: Definisi tabel dilewati selama build (SapProductBuilder mencatat dan menghilangkannya). Tabel atau tampilan tidak akan disalin atau dibuat ke dalam Dataform, sehingga secara efektif mengecualikannya dari deployment tanpa menghapus file definisi sumber.
[table_name].materializationType	string	Tidak	incremental	Cara aset analitik dibuat di BigQuery. Nilai yang Diizinkan: incremental (default): Hanya memproses data baru atau yang diperbarui sejak terakhir kali dijalankan. Direkomendasikan untuk set data transaksional besar guna menghemat biaya. table: Membangun ulang tabel sepenuhnya dari awal pada setiap kali dijalankan. view: Men-deploy aset sebagai tampilan SQL BigQuery (tabel virtual).
[table_name].dataformTags	array[string]	Tidak	[sap, dataproduct]	Tag metadata yang dilampirkan ke aset analitik di Dataform. Ini adalah string arbitrer dan tidak perlu didaftarkan sebelumnya; string ini dapat langsung digunakan untuk menjalankan pipeline secara selektif (misalnya, menggunakan dataform run --tags ...).
[table_name].bigQueryLabels	array[map]	Tidak	-	Daftar pasangan kunci-nilai yang merepresentasikan label BigQuery untuk diterapkan ke aset analitik target (misalnya, key: data_class, value: master).
[table_name].clusterDetails	map	Tidak	—	Opsional. Konfigurasi pengelompokan BigQuery. Lihat Detail pengelompokan.
[table_name].partitionDetails	map	Tidak	—	Opsional. Konfigurasi pembuatan partisi BigQuery. Lihat Detail partisi.

Catatan: Berbeda dengan gaya fondasi data, gaya produk data mendukung **parameter kustom arbitrer** dalam definisi YAML-nya. Parameter tambahan ini diteruskan dengan aman ke dalam konteks kompilasi SQL dan dapat dibaca oleh skrip dan makro Dataform kustom.

Catatan: Selama proses build, `SapProductBuilder` menggabungkan kamus `common` dengan kamus dialek SAP aktif (`ecc` atau `s4`). Jika nama tabel ada di `common` dan kamus dialek aktif (`ecc` atau `s4`), `ProductTableItem` khusus dialek akan menggantikan konfigurasi `common`. Pencarian nama tabel saat mencocokkan kunci kamus dengan file definisi (`*.js` atau `*.sqlx`) tidak peka huruf besar/kecil.

---

Konfigurasi BigQuery lanjutan

Kedua gaya ini memiliki struktur yang sama untuk mengoptimalkan penyimpanan BigQuery dan performa kueri melalui Pengelompokan dan Partisi.

---

Detail pengelompokan

Pengelompokan menempatkan data bersama berdasarkan nilai dalam kolom tertentu. BigQuery mengurutkan data dalam setiap blok penyimpanan menggunakan kolom ini, yang secara signifikan mempercepat kueri yang memfilter (WHERE) atau menggabungkan (JOIN) data di dalamnya.

clusterDetails:
  columns: [bukrs, gjahr]

Referensi parameter

Parameter	Jenis	Wajib	Contoh	Deskripsi
columns	array[string]	Ya	[bukrs, gjahr]	Daftar terurut yang berisi hingga empat nama kolom untuk mengelompokkan tabel. Batasan: Kolom harus alfanumerik dan hanya berisi garis bawah. Urutan kolom dalam daftar menentukan hierarki pengurutan.

---

Detail partisi

Partisi membagi tabel besar menjadi segmen fisik yang lebih kecil berdasarkan nilai kolom tanggal, stempel waktu, atau bilangan bulat. Hal ini mencegah BigQuery memindai seluruh tabel saat kueri hanya meminta rentang hari, bulan, atau ID tertentu.

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day

Referensi parameter

Parameter	Jenis	Wajib	Contoh	Deskripsi
column	string	Ya	budat	Nama kolom yang digunakan untuk memartisi tabel. Hanya boleh berisi karakter alfanumerik dan garis bawah. Jenis kolom harus cocok dengan partitionType.
partitionType	string	Ya	time	Strategi partisi. Nilai yang Diizinkan: time: Membuat partisi menurut unit waktu (kolom Tanggal, Stempel Waktu, atau Tanggal Waktu). DATE: Mempartisi secara eksplisit menurut kolom Tanggal. integer: Mempartisi menurut rentang bilangan bulat.
timeGrain	string	Tidak	day	Wajib jika partitionType adalah time atau DATE. Menentukan perincian partisi waktu. Nilai yang Diizinkan: hour, day, month, year (tidak peka huruf besar/kecil).
rangeStart	integer	Tidak	1	Wajib jika partitionType adalah integer. Nilai awal partisi pertama (inklusif).
rangeEnd	integer	Tidak	1000	Wajib jika partitionType adalah integer. Nilai akhir partisi terakhir (eksklusif).
rangeInterval	integer	Tidak	10	Wajib jika partitionType adalah integer. Lebar setiap interval partisi.

Penting: Jika mengonfigurasi `partitionType: integer`, Anda **harus** menentukan ketiga parameter rentang (`rangeStart`, `rangeEnd`, dan `rangeInterval`) untuk menentukan batas segmen.

---

Contoh

Contoh berikut menunjukkan template konfigurasi untuk modul fondasi data dan produk data, yang menguraikan cara menyesuaikan tabel target, mengoptimalkan tata letak penyimpanan di BigQuery, dan mengonfigurasi jenis perwujudan.

1. Contoh setelan tabel fondasi data kustom

Contoh ini menunjukkan cara mengonfigurasi lapisan fondasi dengan tabel transaksional yang dikelompokkan dan dipartisi (seperti bseg dan ekbe) bersama dengan tabel data standar:

# ==============================================================================
# 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. Contoh setelan tabel produk data kustom

Contoh ini menunjukkan cara mengonfigurasi jenis materialisasi untuk produk data analitik hilir. Kami menetapkan sales_documents transaksional sebagai inkremental untuk mengoptimalkan performa build dan menghemat biaya, sementara tabel data non-transaksional seperti customers dibuat sebagai tabel standar:

# 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]

Panduan cara kerja

Bagian ini memberikan panduan langkah demi langkah untuk tugas konfigurasi umum dan skenario deployment kustom.

Menyesuaikan cakupan tabel dalam modul fondasi data

Untuk menambahkan atau menghapus tabel dalam modul fondasi data yang ada tanpa membuat modul baru atau menjalankan instance pipeline terpisah:

• Salin konfigurasi table_settings.default.yaml default ke direktori konfigurasi ruang kerja Anda (misalnya, config/cortex/sap/foundations/sap/custom_table_settings.yaml).
• Di file baru, tambahkan tabel kustom atau hapus tabel standar yang tidak digunakan di bawah kunci ecc, s4, atau common sesuai kebutuhan:

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

• Perbarui config/config.yaml untuk mereferensikan jalur setelan tabel kustom Anda di properti tableSettings modul:

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'

• Untuk memperkaya skema tabel dari tabel tambahan dengan anotasi (deskripsi tabel dan kolom), buat file anotasi di namespace modul fondasi data yang Anda gunakan. Dalam contoh ini, berdasarkan modulePath: cortex.sap.foundations.sap, jalur untuk menyimpan file anotasi custom_table_name.yaml adalah src/data_modules/cortex/sap/foundations/sap/annotations. Format file anotasi dijelaskan dalam panduan ekstensibilitas untuk fondasi data.

Mengonfigurasi beberapa instance modul fondasi data

Untuk men-deploy dua atau beberapa instance pipeline terpisah dari jenis modul yang sama (misalnya, mendukung beberapa instance SAP, untuk menyegmentasikan tabel, mengisolasi lingkungan, atau menargetkan berbagai set data target).

Sebelum memulai:

• Pastikan tabel sumber ada di set data mentah sumber Anda.
• Saat bekerja dengan modul dasar data SAP, pastikan tabel metadata DD03L berisi kolom dan informasi deskriptor untuk tabel kustom yang ingin Anda masukkan. Lihat persyaratan SAP ERP untuk mengetahui detailnya.

Petunjuk:

• Dalam file config/config.yaml, tambahkan konfigurasi target di bagian data.targets untuk menentukan set data target bagi setiap instance pipeline:

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

• Tentukan beberapa instance modul dalam daftar data.modules.foundations. Beri setiap instance moduleId unik, ID set data targetnya sendiri, dan konfigurasi tableSettings secara opsional:

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"

• Buat file config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml yang menentukan cakupan kustom. 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

• Untuk memperkaya skema tabel dari tabel tambahan dengan anotasi (deskripsi tabel dan kolom), buat file anotasi di namespace modul fondasi data yang Anda gunakan. Dalam contoh ini, berdasarkan modulePath: cortex.sap.foundations.sap, jalur untuk menyimpan file anotasi custom_table_name.yaml adalah src/data_modules/cortex/sap/foundations/sap/annotations. Format file anotasi dijelaskan dalam panduan ekstensibilitas untuk fondasi data.

• Terapkan perubahan dengan menjalankan skrip deployment (uv run cortex-build-and-deploy), lalu jalankan tindakan Dataform seperti yang dijelaskan dalam Langkah-langkah pasca-deployment.