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
config/ Konfigurasi deployment Cortex (Wajib)
Pembuatan namespace baru memerlukan penyiapannya dalam config.yaml.
src/data_modules/custom_namespace_path/data_foundation/data_foundation_module_type Modul fondasi data
Transformasi set data mentah ke fondasi. Setiap fondasi data dipisahkan dalam subdirektori dan terdiri dari:
  • annotations/: Deskripsi tingkat kolom dan bidang.
  • table_settings.default.yaml: Setelan tabel konfigurasi
src/data_modules/custom_namespace_path/data_product/data_product_module_type Definisi produk data
Berisi logika bisnis dan model analisis. Setiap produk dipisahkan dalam subdirektori dan terdiri dari:
  • Readme: Dokumentasi modul
  • manifest.yaml: Mendeklarasikan jenis builder, dependensi, dan konfigurasi.
  • table_settings.default.yaml: Setelan tabel konfigurasi
  • annotations/: Deskripsi tingkat kolom dan bidang.
  • definitions/: File sumber Dataform SQLX atau JS.
src/data_modules/custom_namespace_path/includes/ Helper JavaScript
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
Builder kustom, deployer, dan alat lainnya yang memiliki cakupan 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
        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_module
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_foundation_module # References an existing foundation moduleId 
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_module_type/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. 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 dan 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 data kustom Anda, referensikan sap_product di manifest.yaml Anda:

# src/data_modules/custom_namespace_path/data_product/data_product_module_type/manifest.yaml
type: data_product_module_type
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...

  3. 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 memiliki cakupan eksklusif 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_module_type/builder.py).

  2. Tentukan subclass BaseBuilder atau ProductBuilder di dalamnya:

     from common.builders.base import ProductBuilder

 class UniqueSalesPerformanceBuilder(ProductBuilder):
     # Implement unique build logic here...

  3. Compiler akan otomatis mengimpor dan menjalankan class ini secara dinamis tanpa memerlukan pendaftaran atau dekorator.

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