Menyiapkan namespace kustom

Namespace kustom berfungsi sebagai lingkungan logis untuk mengemas dan mengisolasi fondasi data dan modul produk data analisis Anda. Dengan menjalankan di dalam namespace kustom khusus, Anda dapat mengelola opsi konfigurasi dan deployment secara independen, sehingga memberikan isolasi untuk lingkungan Anda. Manfaat utama dari pemisahan ini adalah Anda dapat dengan mudah mengambil update dan peningkatan mendatang dari namespace cortex di Google Cloud Cortex Framework tanpa risiko mengganti atau merusak modul kustom Anda. Sebaiknya buat modul kustom Anda dalam namespace khusus.

Struktur folder namespace kustom

Folder namespace Cortex Framework digunakan untuk mengemas dan mengisolasi artefak modul kustom. Struktur folder namespace kustom ditentukan dalam tabel:

Jalur direktori Tujuan dan deskripsi Struktur subfolder umum
config/ Konfigurasi deployment Cortex (Wajib)
Pembuatan namespace baru memerlukan penyiapannya dalam config.yaml. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ Modul fondasi data (Opsional)
Transformasi set data mentah ke fondasi. 
-
src/data_modules/custom_namespace_path/data_product/ Definisi produk data (Opsional)
Berisi logika bisnis dan model analisis. Setiap produk dipisahkan dalam subdirektori (misalnya, your_product_name) dan terdiri dari:
  • Readme: Dokumentasi modul
  • manifest.yaml: Mendeklarasikan jenis builder, dependensi, dan konfigurasi.
  • annotations/: Deskripsi tingkat kolom dan kolom.
  • definitions/: File sumber Dataform SQLX atau JS.
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ Helper JavaScript (Opsional)
File JavaScript yang ditempatkan di sini akan otomatis dikemas dan tersedia untuk model Dataform Anda selama kompilasi di jalur namespace (misalnya, includes/custom_namespace/). 
-
src/data_modules/custom_namespace_path/common/ Alat bersama namespace (Opsional)
Builder kustom, deployer, dan alat lainnya yang cakupannya namespace. 
-

Konfigurasi namespace kustom

Namespace baru: custom_namespace dapat ditentukan dengan memperluas bagian yang sesuai dari file config.yaml, membuat direktori baru di bagian src/data_modules/, dan menambahkan aset kode modul baru.

Agar compiler Google Cloud Cortex Framework mengetahui namespace dan modul kustom Anda, Anda harus mendaftarkannya di file konfigurasi global (misalnya, config/config.yaml).

Langkah A: Daftarkan namespace

Di bagian blok data.namespaces, tambahkan metadata namespace Anda:

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

Langkah B: Konfigurasi modul kustom

Daftarkan modul kustom Anda di bagian data.modules.foundation atau data.modules.product. Gunakan format yang dipisahkan titik custom_namespace.module_type untuk kolom type field:

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"

Kode bersama namespace kustom

Namespace kustom mendukung berbagi artefak kode antar-modulnya. Jenis artefak yang didukung adalah:

  • includes - Berisi helper JavaScript yang akan tersedia untuk artefak Dataform Anda. Helper ini dapat ditempatkan di folder: src/data_modules/custom_namespace_path/includes/.
  • builders - Class generator kustom yang dapat mengompilasi kode sumber modul Anda menjadi artefak Dataform. Class ini dapat ditempatkan di src/data_modules/custom_namespace_path/common/.

Memahami dan mereferensikan builder

Builder adalah class generator Python yang mengompilasi file sumber modul Anda menjadi output Dataform fisik. Google Cloud Cortex Framework mengompilasi modul menggunakan urutan resolusi builder tiga tingkat yang fleksibel:

Urutan penyelesaian builder ekstensibilitas Google Cloud Cortex Framework

Gambar 1. Urutan resolusi builder ekstensi Cortex Framework.

Tingkat 1: Builder penggantian global

Framework ini mencakup builder yang sangat andal yang terletak di src/common/builders/. Builder ini terdaftar secara global dan dapat digunakan oleh namespace kustom apa pun.

Misalnya, untuk menggunakan builder produk data SAP standar untuk produk kustom Anda, referensikan sap_product di manifest.yaml:

# 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

Tingkat 2: Builder cakupan namespace

Jika modul di dalam namespace kustom Anda memerlukan compiler khusus, Anda dapat mendaftarkan builder kustom untuk namespace tersebut.

  1. Buat file builder di bagian src/data_modules/custom_namespace_path/common/builders/my_builder.py.

  2. Hias class builder Anda dengan @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. Referensikan di manifest.yaml produk Anda menggunakan builder: my_builder.

Tingkat 3: Builder tingkat produk individual

Untuk pipeline yang sangat unik, Anda dapat menentukan builder yang cakupannya khusus untuk satu produk data.

  1. Cukup buat file bernama builder.py langsung di dalam folder produk data Anda (misalnya, src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py).

  2. Tentukan subclass BaseBuilder atau ProductBuilder di dalamnya:

   from common.builders.base import ProductBuilder

   class UniqueSalesPerformanceBuilder(ProductBuilder):
       # Implement unique build logic here...
  1. Compiler akan otomatis mengimpor dan menjalankan class ini secara dinamis tanpa memerlukan pendaftaran atau dekorator.

Contoh namespace kustom

Di file config/config.yaml, tambahkan blok ini di bagian 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/'

Pada langkah berikutnya: Pembuatan modul fondasi data dan Pembuatan modul produk data, Anda akan mempelajari cara menambahkan modul data ke namespace.