Benutzerdefinierten Namespace einrichten

Benutzerdefinierte Namespaces dienen als logische Umgebungen zum Verpacken und Isolieren Ihrer Datengrundlagen- und Analysedatenproduktmodule. 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, Ihre benutzerdefinierten Module zu überschreiben oder zu beschädigen. Wir empfehlen dringend, Ihre benutzerdefinierten Module in einem dedizierten Namespace zu erstellen.

Ordnerstruktur für benutzerdefinierte Namespaces

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

Verzeichnispfad Zweck und Beschreibung Typische Unterordnerstruktur
config/ Cortex-Bereitstellungskonfiguration (erforderlich)
Beim Erstellen neuer Namespaces müssen diese in config.yaml eingerichtet werden. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ Datengrundlagenmodule (optional)
Transformationen von Rohdaten zu Datensätzen für die Datengrundlage. 
-
src/data_modules/custom_namespace_path/data_product/ Definitionen von Datenprodukten (optional)
Enthält Geschäftslogik und Analysemodelle. Jedes Produkt ist in einem Unterverzeichnis (z. B. your_product_name) getrennt und besteht aus:
  • Readme: Dokumentation des Moduls
  • manifest.yaml: Deklariert den Builder-Typ, die Abhängigkeiten und die Konfiguration.
  • annotations/: Beschreibungen auf Spalten- und Feldebene.
  • definitions/: Dataform SQLX- oder JS-Quelldateien.
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ JavaScript-Helfer (optional)
Alle hier platzierten JavaScript-Dateien werden automatisch verpackt und während der Kompilierung unter dem Namespace-Pfad (z. B. includes/custom_namespace/) für Ihre Dataform-Modelle verfügbar gemacht. 
-
src/data_modules/custom_namespace_path/common/ Gemeinsame Tools für Namespaces (optional)
Benutzerdefinierte Builder, Bereitsteller und andere Tools auf Namespace-Ebene. 
-

Konfiguration benutzerdefinierter Namespaces

Ein neuer Namespace custom_namespace kann definiert werden, indem Sie den entsprechenden Abschnitt der Datei config.yaml erweitern, ein neues Verzeichnis unter src/data_modules/ erstellen und die neuen Modulcode-Assets hinzufügen.

Damit der Google Cloud Cortex Framework-Compiler Ihren benutzerdefinierten Namespace und Ihre 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 Block data.namespaces die Metadaten Ihres Namespace hinzu:

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

Schritt B: Benutzerdefinierte Module konfigurieren

Registrieren Sie Ihre benutzerdefinierten Module unter data.modules.foundation oder data.modules.product. Verwenden Sie für das type Feld das durch Punkte getrennte Format custom_namespace.module_type:

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"

Gemeinsamer Code für benutzerdefinierte Namespaces

Der benutzerdefinierte Namespace unterstützt die gemeinsame Nutzung von Codeartefakten zwischen seinen Modulen. Die unterstützten Artefakttypen sind:

  • 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_path/includes/ platziert werden.
  • builders : Alle benutzerdefinierten Generator-Klassen, mit denen Sie den Quellcode Ihres Moduls in Dataform-Artefakte kompilieren können. Sie können in src/data_modules/custom_namespace_path/common/ platziert werden.

Builder verstehen und referenzieren

Builder sind Python-Generator-Klassen, die die Quelldateien Ihres Moduls in physische Dataform-Ausgaben kompilieren. Google Cloud Cortex Framework kompiliert Module mit einer flexiblen dreistufigen Builder-Auflösungssequenz:

Google Cloud Cortex Framework-Erweiterbarkeit – Abfolge der Schritte zur Fehlerbehebung

Abbildung 1. Auflösungssequenz für Cortex Framework-Erweiterungs-Builder.

Stufe 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-Datenprodukt-Builder für Ihr benutzerdefiniertes Produkt verwenden möchten, verweisen Sie in manifest.yaml auf sap_product:

# 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

Stufe 2: Builder auf Namespace-Ebene

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_path/common/builders/my_builder.py.

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

Stufe 3: Builder auf Ebene einzelner Produkte

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 im Ordner Ihres Datenprodukts (z.B. src/data_modules/custom_namespace_path/data_product/data_product_id/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...
  1. Der Compiler importiert und führt diese Klasse automatisch dynamisch aus, ohne dass eine Registrierung oder Decorators erforderlich sind.

Beispiel für einen benutzerdefinierten Namespace

Fügen Sie in der Datei config/config.yaml unter data.namespaces diesen Block hinzu:

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

In den nächsten Schritten: Datengrundlagenmodul erstellen und Datenproduktmodul erstellen erfahren Sie, wie Sie dem Namespace Datenmodule hinzufügen.