Configurazione di uno spazio dei nomi personalizzato

Gli spazi dei nomi personalizzati fungono da ambienti logici per raggruppare e isolare i moduli di base dei dati e dei prodotti di dati analitici. L'esecuzione all'interno di uno spazio dei nomi personalizzato dedicato consente di gestire le opzioni di configurazione e deployment in modo indipendente, fornendo l'isolamento per l'ambiente. Un vantaggio fondamentale di questa separazione è che puoi estrarre senza problemi aggiornamenti e miglioramenti futuri dallo spazio dei nomi cortex in Google Cloud Cortex Framework senza il rischio di sovrascrivere o danneggiare i tuoi moduli personalizzati. Ti consigliamo vivamente di creare i moduli personalizzati all'interno di uno spazio dei nomi dedicato.

Struttura delle cartelle dello spazio dei nomi personalizzato

Le cartelle dello spazio dei nomi di Cortex Framework vengono utilizzate per creare pacchetti e isolare gli artefatti dei moduli personalizzati. La struttura delle cartelle di uno spazio dei nomi personalizzato è definita nella tabella:

Percorso directory Scopo e descrizione
config/ Configurazione del deployment di Cortex (obbligatorio)
La creazione di nuovi spazi dei nomi richiede la loro configurazione in config.yaml.
src/data_modules/custom_namespace/data_foundation/data_foundation_module_type Moduli di base dei dati
Trasformazioni dei set di dati non elaborati in set di dati di base. Ogni base di dati è separata in una sottodirectory e consiste in:
  • annotations/: Descrizioni a livello di colonna e campo.
  • table_settings.default.yaml: configurazione delle impostazioni della tabella
src/data_modules/custom_namespace/data_product/data_product_module_type Definizioni dei prodotti di dati
Contiene la logica di business e i modelli analitici. Ogni prodotto è separato in una sottodirectory e consiste in:
  • Readme: Documentazione del modulo
  • manifest.yaml: dichiara il tipo di builder, le dipendenze e la configurazione.
  • table_settings.default.yaml: configurazione delle impostazioni della tabella
  • annotations/: Descrizioni a livello di colonna e campo.
  • definitions/: file sorgente SQLX o JS di Dataform.
src/data_modules/custom_namespace/includes/ Helper JavaScript
Tutti i file JavaScript inseriti qui vengono automaticamente pacchettizzati e resi disponibili per i modelli Dataform durante la compilazione nel percorso dello spazio dei nomi (ad esempio, includes/custom_namespace/).
src/data_modules/custom_namespace/common/ Strumenti condivisi dello spazio dei nomi
Builder personalizzati, strumenti di deployment e altri strumenti con ambito a livello di spazio dei nomi.

Configurazione personalizzata dello spazio dei nomi

Un nuovo spazio dei nomi: custom_namespace può essere definito estendendo la sezione corrispondente del file config.yaml, creando una nuova directory in src/data_modules/ e aggiungendo i nuovi asset di codice del modulo.

Per rendere il compilatore Google Cloud Cortex Framework consapevole del tuo spazio dei nomi e dei tuoi moduli personalizzati, devi registrarli nel file di configurazione globale (ad es. config/config.yaml).

Passaggio A: registra lo spazio dei nomi

Nel blocco data.namespaces, aggiungi i metadati dello spazio dei nomi:

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name:  custom_namespace    # <-- Name of custom namespace
      path:  custom_namespace/  # <-- Folder name that is used for custom namespace, points to subdirectory of 'src/data_modules/'

Passaggio B: configura i moduli personalizzati

Registra i tuoi moduli personalizzati in data.modules.foundation o data.modules.product. Utilizza il formato separato da punti custom_namespace.module_type per il campo type:

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_data_foundation_module_type
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/table_settings.default.yaml"
        # Custom table settings file, relative to 'config/' directory
        tableSettings: "custom_namespace/data_foundation/data_foundation_module_type/table_settings.yaml"
        
    product:
      - moduleId: custom_namespace_data_product_module_type
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_data_foundation_module_type # References an existing foundation moduleId 
        dataTargetId: product_target
        # Custom table settings file, relative to 'config/' directory
        # tableSettings: "custom_namespace/data_product/data_product_module_type/table_settings.yaml"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_product/data_product_module_type/table_settings.default.yaml"

Codice condiviso dello spazio dei nomi personalizzato

Lo spazio dei nomi personalizzato supporta la condivisione di artefatti di codice tra i suoi moduli. I tipi di artefatto supportati sono:

  • includes: contiene tutti gli helper JavaScript che verranno resi disponibili per gli artefatti Dataform. Possono essere inseriti nella cartella: src/data_modules/custom_namespace/includes/.
  • builder: qualsiasi classe di generatori personalizzati che può compilare il codice sorgente del modulo in artefatti Dataform. Possono essere inseriti in src/data_modules/custom_namespace/common/.

Comprendere e fare riferimento ai builder

I builder sono classi generatore Python che compilano i file di origine del modulo in output Dataform. Google Cloud Cortex Framework compila i moduli utilizzando una sequenza di risoluzione del builder a tre livelli flessibile:

Sequenza di risoluzione dei builder di estensibilità di Google Cloud Cortex Framework

Figura 1. Sequenza di risoluzione dei builder di estensibilità di Cortex Framework.

Livello 1: costruttori di fallback globali

Il framework include generatori molto robusti che si trovano in src/common/builders/. Questi generatori sono registrati a livello globale e possono essere utilizzati da qualsiasi spazio dei nomi personalizzato.

Ad esempio, per utilizzare i generatori di prodotti di dati SAP standard per il tuo prodotto di dati personalizzato, fai riferimento a sap_product in manifest.yaml:

# src/data_modules/custom_namespace/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

Livello 2: builder con ambito a livello di spazio dei nomi

Se i moduli all'interno dello spazio dei nomi personalizzato richiedono un compilatore specializzato, puoi registrare un builder personalizzato per lo spazio dei nomi.

  1. Crea un file builder in src/data_modules/custom_namespace/common/builders/my_builder.py.

  2. Decora la tua classe di builder con @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. Fai riferimento a questo elemento nella manifest.yaml del tuo prodotto utilizzando builder: my_builder.

Livello 3: builder a livello di singolo prodotto

Per le pipeline altamente uniche, puoi definire un builder con ambito esclusivo per un singolo prodotto di dati.

  1. Basta creare un file denominato builder.py direttamente all'interno della cartella del prodotto di dati (ad es. src/data_modules/custom_namespace/data_product/data_product_module_type/builder.py).

  2. Definisci una sottoclasse di BaseBuilder o ProductBuilder al suo interno:

     from common.builders.base import ProductBuilder

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

  3. Il compilatore importerà ed eseguirà automaticamente questa classe in modo dinamico senza richiedere alcuna registrazione o decoratore.

Nei passaggi successivi, Creazione del modulo della base di dati e Creazione del modulo del prodotto di dati, imparerai ad aggiungere moduli di dati allo spazio dei nomi.