Benutzerdefinierten Namespace einrichten

Benutzerdefinierte Namespaces dienen als logische Umgebungen zum Verpacken und Isolieren Ihrer Datenbasis und Ihrer analytischen Datenproduktmodule. Wenn Sie in einem dedizierten benutzerdefinierten Namespace ausgeführt werden, können Sie Konfigurations- und Bereitstellungsoptionen unabhängig verwalten und so Ihre Umgebung isolieren. Ein wichtiger Vorteil dieser Trennung besteht darin, dass Sie zukünftige Updates und Verbesserungen nahtlos aus dem cortex-Namespace im Google Cloud Cortex Framework abrufen können, ohne das Risiko, dass Ihre benutzerdefinierten Module überschrieben oder beschädigt werden. Wir empfehlen dringend, benutzerdefinierte Module in einem dedizierten Namespace zu erstellen.

Hinweis :Ein Namespace kann mehrere Module für die Datenbasis und das Datenprodukt enthalten.

Benutzerdefinierte Namespace-Ordnerstruktur

Die Namespace-Ordner des Cortex Framework werden verwendet, um benutzerdefinierte Modul-Artefakte zu verpacken und zu isolieren. Die Ordnerstruktur eines benutzerdefinierten Namespace ist in der Tabelle definiert:

Verzeichnispfad	Zweck und Beschreibung
config/	Cortex-Deployment-Konfiguration (erforderlich) Zum Erstellen neuer Namespaces ist die Einrichtung in config.yaml erforderlich.
src/data_modules/custom_namespace/data_foundation/data_foundation_module_type	Module für die Datenbasis Transformationen von Rohdaten- in Grundlage-Datasets. Jede Data Foundation ist in einem Unterverzeichnis enthalten und besteht aus: annotations/: Beschreibungen auf Spalten- und Feldebene. table_settings.default.yaml: Konfiguration der Tabelleneinstellungen
src/data_modules/custom_namespace/data_product/data_product_module_type	Definitionen von Datenprodukten Enthält Geschäftslogik und Analysemodelle. Jedes Produkt befindet sich in einem separaten Unterverzeichnis und besteht aus: Readme: Dokumentation des Moduls manifest.yaml: Deklariert den Builder-Typ, die Abhängigkeiten und die Konfiguration. table_settings.default.yaml: Konfiguration der Tabelleneinstellungen annotations/: Beschreibungen auf Spalten- und Feldebene. definitions/: Dataform-SQLX- oder JS-Quelldateien.
src/data_modules/custom_namespace/includes/	JavaScript-Helfer Alle JavaScript-Dateien, die hier abgelegt werden, werden automatisch verpackt und sind während der Kompilierung für Ihre Dataform-Modelle unter dem Namespace-Pfad (z. B. includes/custom_namespace/) verfügbar.
src/data_modules/custom_namespace/common/	Namespace-Tools Benutzerdefinierte Builder, Deployer und andere Tools mit Namespace-Bereich.

Benutzerdefinierte Namespace-Konfiguration

Ein neuer Namespace: custom_namespace kann definiert werden, indem der entsprechende Abschnitt der Datei config.yaml erweitert, ein neues Verzeichnis unter src/data_modules/ erstellt und die neuen Modulcode-Assets hinzugefügt werden.

Damit der Compiler des Google Cloud Cortex Framework Ihren benutzerdefinierten Namespace und Ihre benutzerdefinierten Module erkennt, müssen Sie sie in Ihrer globalen Konfigurationsdatei (z.B. config/config.yaml) registrieren.

Schritt A: Namespace registrieren

Fügen Sie unter dem data.namespaces-Block Ihre Namespace-Metadaten hinzu:

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

Schritt B: Custom Modules konfigurieren

Registrieren Sie Ihre benutzerdefinierten Module unter data.modules.foundation oder data.modules.product. Verwenden Sie für das Feld type das durch Punkte getrennte Format custom_namespace.module_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"

Hinweis :data_foundation_module_type und data_product_module_type sind technisch bereinigte Strings des Modulnamens (Kleinbuchstaben, wobei Sonderzeichen und Leerzeichen durch Unterstriche ersetzt werden). Muss mit dem Attribut type: in der Datei src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/manifest.yaml oder src/data_modules/custom_namespace/data_product/data_product_module_type/manifest.yaml übereinstimmen.

Freigegebener Code für benutzerdefinierten Namespace

Der benutzerdefinierte Namespace unterstützt die gemeinsame Nutzung von Code-Artefakten zwischen seinen Modulen. Folgende Artefakttypen werden unterstützt:

• includes: Enthält alle JavaScript-Helfer, die für Ihre Dataform-Artefakte verfügbar gemacht werden. Sie können im Ordner src/data_modules/custom_namespace/includes/ platziert werden.
• Builders: Alle benutzerdefinierten Generator-Klassen, mit denen der Quellcode Ihres Moduls in Dataform-Artefakte kompiliert werden kann. Sie können in src/data_modules/custom_namespace/common/ platziert werden.

Builder verstehen und referenzieren

Builders sind Python-Generator-Klassen, mit denen die Modulquelldateien in Dataform-Ausgaben kompiliert werden. Im Google Cloud Cortex Framework werden Module mit einer flexiblen dreistufigen Builder-Auflösungssequenz kompiliert:

Abbildung 1. Auflösungssequenz für die Erweiterbarkeit des Cortex Framework Frameworks.

Tier 1: Globale Fallback-Builder

Das Framework enthält sehr robuste Builder in src/common/builders/. Diese Builder sind global registriert und können von jedem benutzerdefinierten Namespace verwendet werden.

Wenn Sie beispielsweise die Standard-SAP-Data-Product-Builder für Ihr benutzerdefiniertes Datenprodukt verwenden möchten, verweisen Sie in Ihrem manifest.yaml auf sap_product:

# 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

Tier 2: Namespace-bezogene Builder

Wenn für Module in Ihrem benutzerdefinierten Namespace ein spezieller Compiler erforderlich ist, können Sie einen benutzerdefinierten Builder für diesen Namespace registrieren.

1. Erstellen Sie eine Builder-Datei unter src/data_modules/custom_namespace/common/builders/my_builder.py.

2. Dekorieren Sie Ihre Builder-Klasse mit @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. Verweisen Sie mit builder: my_builder in der manifest.yaml Ihres Produkts darauf.

Tier 3: Ersteller auf Produktebene

Für sehr spezielle Pipelines können Sie einen Builder definieren, der ausschließlich für ein einzelnes Datenprodukt gilt.

1. Erstellen Sie einfach eine Datei mit dem Namen builder.py direkt in Ihrem Datenproduktordner (z.B. src/data_modules/custom_namespace/data_product/data_product_module_type/builder.py).

2. Definieren Sie darin eine abgeleitete Klasse von BaseBuilder oder ProductBuilder:

    from common.builders.base import ProductBuilder
   
    class UniqueSalesPerformanceBuilder(ProductBuilder):
        # Implement unique build logic here...
   

3. Der Compiler importiert und führt diese Klasse automatisch dynamisch aus, ohne dass eine Registrierung oder Dekoratoren erforderlich sind.

In den nächsten Schritten Data Foundation-Modul erstellen und Data Product-Modul erstellen erfahren Sie, wie Sie dem Namespace Datenmodule hinzufügen.

---

• Nächster Schritt: Modul für die Datengrundlage erstellen
• Zurück zur Übersicht