Konfiguration des Deployments

Auf dieser Seite werden die Bereitstellungskonfigurationsoptionen für das Cortex Framework in den folgenden Bereichen erläutert:

Auf dieser Seite finden Sie auch Anleitungen mit Schritt-für-Schritt-Anleitungen für gängige Bereitstellungsanwendungsfälle und ‑szenarien.

Konfigurationsdatei: config/config.yaml

Die Datei config/config.yaml, die in der Regel aus der Vorlage config/config.yaml.example initialisiert wird, dient als primäre Konfiguration für die Cortex Framework-Bereitstellung. Die Konfiguration ist in folgende strukturelle Blöcke unterteilt:

  1. Build-Umgebung (buildEnvironment): Steuert die Build-Orchestrierungsebene und gibt das zentrale Google Cloud Projekt an, in dem Zwischenberechnungen von Metadaten, Datenbankvalidierungen und Schemasuchen abgerechnet und ausgeführt werden.
  2. Daten (data): Regelt die logische Datenarchitektur. In diesem Block werden Dataset-Standorte, Namespace-Grenzen, Verbindungsdetails für Rohdatenquellen, Zieldatasets und die Datenmodulinstanzen (foundations, catalogs und products) konfiguriert.
  3. Bereitstellung (deployment): Konfiguriert Bereitstellungen für physische Zielsysteme. Hier werden die Details des Dataform-Repositorys (Projekt-ID, Speicherort, Repository-Name und Entwicklungsarbeitsbereich) angegeben, in dem kompilierte SQLX/JS-Transformationspipelines bereitgestellt werden.

In den folgenden Abschnitten werden die einzelnen Blöcke detailliert beschrieben.

Build-Umgebung

Das Projekt der Build-Umgebung ist das Projekt, das für Build-Aktionen wie BigQuery-Jobs, die DD03L lesen, abgerechnet wird.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

In der folgenden Tabelle werden die Parameter der Build-Umgebung beschrieben.

Parameter Bedeutung Standardwert Beschreibung
buildEnvironment.buildProjectId Build-Projekt-ID YOUR_BUILD_PROJECT_ID Google Cloud : Projekt-ID, in der Buildvorgänge ausgeführt werden.

Übersicht über den Bereich „Daten“

Im Bereich data: der Konfigurationsdatei werden Ihre Datenquellen, Ziele und die spezifischen Module für die Datenbasis und die Datenprodukte definiert. Die allgemeine Struktur sieht so aus:

data:
   # Geographic location for BigQuery datasets (for example: US, EU, us-central1)
   # For full list see: https://docs.cloud.google.com/cortex/docs/supported-locations
  bigQueryLocation: US
  # List of namespaces for data foundation and product modules.
  namespaces:
    - name: cortex
      path: ../src/data_modules/cortex
  # List of datasets mapping.
  datasets:
    - ...

  # Configuration for data foundation, data product, and external catalog modules.
  modules:
    # List of foundation modules.
    foundations:
    - ... 
    # List of external catalog modules.
    catalogs:
    - ...
    # List of data product modules.
    products:
    - ...

Daten: BigQuery-Standort

Definiert den Speicherort der BigQuery-Quell- und ‑Zieldatasets.

Parameter Bedeutung Standardwert Beschreibung
data.bigQueryLocation BigQuery-Standort US Speicherort des BigQuery-Datasets, z. B. US, us-central1 oder europe-west1.

Daten: Cortex-Namespace

Definiert den Namespace des Cortex Framework.

Parameter Bedeutung Standardwert Beschreibung
data.namespaces.name Namespace-Name - Name des Cortex Framework-Namespace. Beispiel: cortex.
data.namespaces.path Namespace-Pfad - Cortex Framework-Namespacepfad für Unterverzeichnisse, die im Ordner „src“ und „config“ verwendet werden. Beispiel: cortex.

Daten: BigQuery-Quellen und ‑Zieldatasets

Die Liste der Datasets definiert die eingehenden Rohdaten-Verbindungspunkte und ausgehenden Speicherorte für das Framework. Für jedes Dataset wird eine eindeutige Kennung registriert, die einem bestimmten Google Cloud -Projekt und BigQuery-Dataset zugeordnet ist.

Auf Datasets wird in den Modulen anhand ihrer eindeutigen ID verwiesen.

# Dataset mapping
datasets:
  - id: sap_raw
    projectId: YOUR_SOURCE_PROJECT_ID
    datasetId: cortex_sap_raw
  - id: sap_foundation
    projectId: YOUR_TARGET_PROJECT_ID
    datasetId: cortex7_sap_data_foundation

In der folgenden Tabelle werden die Parameter für die Dataset-Zuordnung beschrieben.

Parameter Bedeutung Standardwert Beschreibung
data.datasets.id Dataset-ID - Definiert eine eindeutige Kennung für den Datensatz, z.B. sap_raw oder sap_foundation.
data.datasets.projectId Projekt-ID - Verweist auf die Google Cloud Projekt-ID, in der das Dataset gehostet wird.
data.datasets.datasetId BigQuery-Dataset-ID - Verweist auf den tatsächlichen Namen des BigQuery-Datasets.

Daten: Module

Die Module definieren die Struktur und die Komponenten der Dataform-Datenpipelines.

Daten: Module: Grundlagen

In diesem Abschnitt werden die Module der Data Foundation-Ebene konfiguriert, die Daten aus der Rohdatenebene in eine standardisierte Darstellung der neuesten Datensätze der Quelldaten verarbeiten. Wenn die Quelle direkt eine Ansicht der neuesten Datensätze bereitstellt oder solche Transformationen vom Connector des Quellsystems ausgeführt werden, kann das Modul als externe Datenfundierungsquelle konfiguriert werden.

modules:
  # List of foundation modules.
  foundations:
    # Unique identifier for the module instance.
    - moduleId: erp
      # Path of the module format: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap}, for example, cortex.sap.foundations.sap.
      modulePath: cortex.sap.foundations.sap
      # Reference to the source dataset ID.
      dataSourceId: sap_raw
      # Reference to the target dataset ID.
      dataTargetId: sap_foundation
      # Module-specific configuration settings.
      moduleSettings:
        # SAP version (for example, ecc, s4).
        sapVersion: ecc
        # SAP client number.
        mandt: "100"
      # Whether the module is enabled.
      enabled: true
      # Whether the foundation is external (does not create target dataset).
      external: false
      # Custom table settings file, relative to 'config/' file directory
      # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml' (e.g. 'cortex/sap/foundations/sap/table_settings.yaml')
      # Default path: '../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'
      tableSettings: "custom_table_settings.yaml"

In der folgenden Tabelle werden die Parameter der Data Foundation-Module für die modules.foundations-Konfiguration beschrieben.

Parameter Bedeutung Standardwert Beschreibung
moduleId Modulkennung erp Eindeutige Kennung für eine bestimmte Instanz eines Data Foundation-Transformationsmoduls.
modulePath Modulpfad cortex.sap.foundations.sap Definiert den Namespace-Pfad zum angewendeten Modul, zur Geschäftslogik oder zur Vorlage. Format: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap} (z. B. cortex.sap.foundations.sap).
dataSourceId Quellenlink sap_raw Verweist auf die „id“ aus der Liste data.datasets, um Daten abzurufen.
dataTargetId Ziellink sap_foundation Verweist auf die „id“ aus der Liste data.datasets, um Daten zu übertragen.
moduleSettings.sapVersion SAP-Systemversion ecc Gilt nur für SAP-Datenquellen. Legt die quellspezifische Logik für ecc- (ECC) oder s4-Systeme (S/4HANA) fest.
moduleSettings.mandt SAP-Client (Mandant) 100 Gilt nur für SAP-Datenquellen. Die dreistellige SAP-Client-Kennung, die zum Filtern von Datenzeilen verwendet wird.
enabled Modul aktivieren true Gibt an, ob das Modul aktiviert ist.
external Externe Stiftung false Gibt an, ob die Grundlage extern ist (kein Zieldataset wird erstellt).
tableSettings Tabelleneinstellungen src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml Pfad zur benutzerdefinierten Konfigurationsdatei für Tabelleneinstellungen, relativ zu dieser Konfigurationsdatei.
Empfohlener Pfad: relativ zum Verzeichnis „config/“: „{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml“
Standardpfad: „../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml“

Daten – Module – Kataloge

Mit externen Lakehouse-Katalogen kann das Cortex Framework externe Tabellen aus BigLake Delta Sharing-Katalogen und -Freigaben ohne physische Manifeste aufnehmen.

modules:
  # List of external catalog modules.
  catalogs:
    # Unique identifier for the catalog.
    - id: sap_bdc_catalog
      # Type of the catalog.
      type: lakehouse_delta_share
      # Logical namespace prefixes bound by this catalog.
      bindsNamespaces: [sap_bdc]
      # Connection settings for the catalog.
      connectionSettings:
        # Unique identifier for the catalog.
        catalogId: sap_bdc_catalog
        # Unique identifier for the project hosting the catalog.
        projectId: sap_bdc_delta_share
        # Geographic region location for the catalog.
        location: europe-west3
        # List of shares to import.
        shares:
          - shareId: customer_v1_he2_100_p8123
          - shareId: salesorder_v1_he2_100_p8124
      # Whether the catalog is enabled.
      # enabled: true

In der folgenden Tabelle werden die Konfigurationsparameter für externe Kataloge beschrieben.

Parameter Bedeutung Standardwert Beschreibung
id Katalog-ID - Eindeutige Kennung für eine bestimmte externe Katalogmodulinstanz.
type Katalogtyp lakehouse_delta_share Typ des Katalogs. Unterstützt lakehouse_delta_share.
bindsNamespaces Gebundene Namespaces - Eine Liste der logischen Namespace-Präfixe, die an diesen Katalog gebunden sind (z.B. [sap_bdc]).
connectionSettings.catalogId Physische Katalog-ID - Physische Katalog-ID. Entspricht in der Regel der Modul-ID.
connectionSettings.projectId Projekt-ID - Die Google Cloud Projekt-ID, unter der die Katalogverbindung verwaltet wird.
connectionSettings.location Standort - Der geografische Standort des Katalogs.
connectionSettings.shares Geteilte Inhalte - Liste der zu importierenden Delta Sharing-Freigaben. Jeder Share muss ein shareId enthalten.
enabled Katalog aktivieren true Gibt an, ob der Katalog aktiviert ist.

Daten: Module: Produkte

In Datenproduktmodulen werden die Aggregationen, Berechnungen und Joins definiert, die erforderlich sind, um Rohdaten in Statistiken umzuwandeln, die bestimmte geschäftliche Anwendungsfälle erfüllen.

Bei der Konfiguration der Datenprodukte können Sie eine eindeutige ID festlegen, Abhängigkeiten definieren sowie auf das Datenfundierungsmodul und das Zieldataset verweisen, in dem die Ergebnisse gespeichert werden.

Die detaillierte Konfiguration der angegebenen Datenprodukte wird in Dateien definiert, auf die mit dem Schlüssel tableSettings verwiesen wird.

modules:
  # List of data product modules.
  products:
    # Unique identifier for the data product instance.
    - moduleId: sap_purchasing_organizational_structure
      # Path of the data product (namespaced).
      modulePath: cortex.sap.products.purchasing_organizational_structure
      # Map of module dependencies.
      dependencyBindings:
        sapModule: erp
      # Reference to the target dataset ID.
      dataTargetId: product_target
      # Whether the module is enabled.
      enabled: true
      # Whether this data product is synced to the Knowledge Catalog. Defaults to true.
      syncToKc: true

      # Custom table settings file, relative to 'config/' file directory
      # Recommended path: '{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml'
      # If omitted, defaults to '../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml'
      # tableSettings: "custom_dataproduct_table_settings.yaml"

In der folgenden Tabelle werden die Parameter für die Datenproduktmodule für die modules.products-Konfiguration beschrieben.

Parameter Bedeutung Standardwert Beschreibung
moduleId Modulkennung - Eindeutige Kennung für eine bestimmte Transformationsmodulinstanz.
modulePath Modulpfad - Definiert den Namespace-Pfad zum angewendeten Modul, zur angewendeten Geschäftslogik oder zur angewendeten Vorlage. Format: {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}, z. B. cortex.sap.products.purchasing_organizational_structure, definiert im Ordner src/data_modules/{namespace_dir}/{system_type}/products/{product_name}.
dataTargetId Ziellink product_target Verweist auf die „id“ aus der Zielliste, an die Daten gesendet werden sollen.
dependencyBindings Upstream-Abhängigkeit sapModule: erp Gibt Zuordnungen zum Erfüllen von Modulabhängigkeiten an. Beispiel: sapModule wird erp zugeordnet.
enabled Modul aktivieren true Gibt an, ob das Modul aktiviert ist.
syncToKc Knowledge Catalog-Synchronisierung true Gibt an, ob dieses Datenprodukt mit dem Knowledge Catalog synchronisiert wird.
tableSettings Tabelleneinstellungen src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml Pfad zur benutzerdefinierten Konfigurationsdatei für Tabelleneinstellungen, relativ zu dieser Konfigurationsdatei.
Empfohlener Pfad: relativ zum Verzeichnis „config/“: „{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml“
Standardpfad: „../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml“

Bereitstellungsumgebung

Das Cortex Framework verwendet Dataform, um SQL-Transformationen in BigQuery zu orchestrieren. Im deployment:-Block wird die Dataform-Konfiguration definiert, die für die Ausführung der Datenpipelines verantwortlich ist. Dazu gehören das Repository-Projekt, der Standort, der Repository-Name und der Name des Dataform-Arbeitsbereichs.

deployment:
  targets:
    - type: dataform
      enabled: true
      targetSettings:
        repositoryProjectId: YOUR_REPO_PROJECT_ID
        repositoryRegion: us-central1
        repositoryName: cortex-repository
        workspaceName: dev
        # serviceAccount: "example@example.com"

In der folgenden Tabelle werden die Standortparameter für Bereitstellungsziele (deployment.targets:) beschrieben.

Parameter Bedeutung Standardwert Beschreibung
type Art der Bereitstellung dataform Typ der Bereitstellungsziele.
enabled Aktiviert/ Deaktiviert true Gibt an, ob das angegebene Bereitstellungsziel aktiviert oder deaktiviert ist.
targetSettings.repositoryProjectId Repository-Projekt-ID YOUR_REPO_PROJECT_ID Die Google Cloud Projekt-ID, in der das Dataform-Repository verwaltet wird.
targetSettings.repositoryRegion Repository-Region us-central1 Die Google Cloud -Region für das Dataform-Repository (z. B. us-central1 oder europe-west1).
targetSettings.repositoryName Repository-Name cortex-repository Der spezifische Name des Dataform-Repositorys.
targetSettings.workspaceName Name des Arbeitsbereichs dev Der spezifische Dataform-Arbeitsbereich, der für den Bereitstellungszyklus verwendet wird.
targetSettings.serviceAccount E-Mail-Adresse des Dienstkontos - Standard-E-Mail-Adresse des Dienstkontos für die Ausführung von Dataform-Repositories.

Konfigurationsdatei: table_settings.yaml

In dieser Anleitung wird beschrieben, wie Sie mit der Datei table_settings.yaml Tabellen für die Datengrundlage und das Datenprodukt im Google Cloud Cortex Framework konfigurieren.

Die datenmodulspezifische table_settings.yaml-Datei steuert, wie Rohquellentabellen angepasst und wie analytische Datenmodelle in BigQuery materialisiert werden. Mit dieser Datei können Sie Tags, Materialisierungsstrategien und erweiterte BigQuery-Leistungsfunktionen wie Partitionierung oder Clustering konfigurieren.

Dynamische Auflösung von Abhängigkeiten

Standardmäßig optimiert Cortex Framework den Bereitstellungs-Footprint und die Ausführungszeit, indem nur die Fundamenttabellen bereitgestellt und kompiliert werden, die als Abhängigkeiten Ihrer aktivierten Datenprodukte erforderlich sind. Wenn für eine in table_settings.yaml konfigurierte Tabelle keine aktiven Downstream-Datenprodukte vorhanden sind, die von ihr abhängen, wird sie bei der Bereitstellung ausgelassen.

Wenn Sie diese Optimierung überschreiben und die Bereitstellung einer Foundation-Tabelle erzwingen möchten, können Sie das Attribut deployAlways auf true festlegen (siehe Referenz für Stilparameter für Data Foundations).

Im Google Cloud Cortex Framework kann jedem Modul (Foundation oder Produkt) in der Bereitstellungskonfigurationsdatei eine bestimmte Datei mit Tabelleneinstellungen zugewiesen werden: config/config.yaml mit dem Attribut tableSettings.

Konfigurationspfade

  • Benutzerdefinierte Einstellungen (empfohlen): Wenn Sie das Tabellenverhalten anpassen möchten, kopieren Sie die Standarddatei in Ihr Konfigurationsverzeichnis, ändern Sie sie und verweisen Sie in config/config.yaml auf den Pfad. Die empfohlenen Pfade (relativ zum Verzeichnis config/) sind:
    • Foundation-Module:namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml (z.B. config/cortex/sap/foundations/sap/table_settings.yaml)
    • Produktmodule:namespace_dir/system_type/products/product_name/custom_table_settings.yaml (z.B. config/cortex/sap/products/accounting_documents/table_settings.yaml)
  • Standard-Fallback:Wenn tableSettings weggelassen wird, greift das Framework automatisch auf Folgendes zurück:
    • Foundation-Module:../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
    • Produktmodule:../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

Konfigurationsstile

Je nach Kategorie des Moduls gibt es zwei verschiedene Schemastile für table_settings.yaml:

  1. Data Foundation-Stil:Listenbasierte Zuordnung, mit der die Beziehungen zwischen Quell- und Zielschema, die CDC-Verarbeitung (Change Data Capture) und das BigQuery-Layout definiert werden. Das Layout der Einstellungen für die Data Foundation-Tabelle ist quellsystemspezifisch.

  2. Data Product Style (Stil des Datenprodukts): Eine kartenbasierte Zuordnung (Wörterbuch), die definiert, wie Analyseansichten oder ‑tabellen materialisiert (z.B. als Ansichten, Tabellen oder inkrementelle Tabellen) und optimiert werden.

Beide Stile unterstützen drei Abschnitte auf Stammebene, um Konfigurationen nach Quellsystemversion zu trennen (hauptsächlich für SAP Data Foundation und SAP-abhängige Produkte):

  • ecc: Einstellungen, die nur bei der Bereitstellung eines SAP ECC-Quellsystems angewendet werden.
  • s4: Einstellungen, die nur bei der Bereitstellung eines SAP S/4HANA-Quellsystems angewendet werden.
  • common: Einstellungen, die unabhängig von der SAP-Version angewendet werden (für angepasste oder universelle Einstellungen).

Data Foundation-Stil für SAP ERP

In einem Data Foundation-Modul für SAP ERP-Quellsysteme ist die Datei table_settings.yaml als Liste von Tabellenelementen unter den Schlüsseln ecc, s4 und common strukturiert. Jedes Element ordnet eine Rohquelltabelle einer angepassten Zieltabelle zu und konfiguriert die BigQuery-Einstellungen.

Beispiel für YAML-Syntax

common:
  - source:
      tableName: raw_custom_bkpf
      sapTableName: bkpf
      isCdc: true
    target:
      tableName: bkpf # Optional: defaults to source tableName if omitted
      bigQueryLabels:
        - key: data_class
          value: transactional
        - key: line_of_business
          value: finance
      dataformTags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day
    deployAlways: false

Parameterverweis

Parameter Typ Erforderlich Standard / Beispiel Beschreibung
[].source object Ja [] Beschreibt die Tabelle im Inbound-Quellsystem der Datenbasis (z.B. „sap_raw“). Weitere Informationen finden Sie unter „Quelleneinstellungen“.
[].target object Ja [] Beschreibt die Zieltabelle in den Datasets der Datenbasis (z.B. „sap_data_foundation“). Weitere Informationen finden Sie unter Zieleinstellungen.
ecc | s4 | common string Nein [] Version oder Dialekt des Quellsystems.
[].deployAlways boolean Nein false Wenn true, wird die Tabelle immer bereitgestellt und erstellt, auch wenn sie aufgrund von Optimierungsregeln möglicherweise übersprungen würde. Siehe auch Dynamische Auflösung von Abhängigkeiten
Quelleneinstellungen

Definiert die Eigenschaften der Rohdaten-Eingangstabelle.

Parameter Typ Erforderlich Standard / Beispiel Beschreibung
tableName string Ja - Der Name der Rohquelltabelle in BigQuery (ohne Berücksichtigung der Groß- und Kleinschreibung), wie sie vom Connector aus dem Quellsystem importiert wird .
sapTableName string Nein - Der SAP-Tabellenname (nicht case-sensitive), wie in den Metadatentabellen des Quellsystems definiert (z.B. „DD03L“). Falls definiert, wird dieser Parameter als Name für die entsprechende Data Foundation-Tabelle verwendet.
isCdc boolean Nein true Gibt an, ob die Quelltabelle CDC-Logs (Change Data Capture) enthält.

• true (Standard): Das Framework verarbeitet CDC-Logs (mit Datensatz-Zeitstempeln und Vorgangs-Flags), um den letzten angepassten Status zu rekonstruieren.

• false: Die Tabelle wird als vollständiger Snapshot verarbeitet.
Zieleinstellungen

Definiert das Layout der angepassten Ausgabetabelle im Ziel-Dataset.

Parameter Typ Erforderlich Standard / Beispiel Beschreibung
tableName string Nein *(Same as source)* Der Name der zu erstellenden angepassten Zieltabelle. Wenn nichts angegeben ist, wird standardmäßig das Framework der Quelle tableName verwendet.
dataformTags array[string] Nein [sap, finance] Eine Liste der Metadatentags, die an die angepasste Aktion in Dataform angehängt sind. Das sind beliebige Strings, die nicht vorab registriert oder in anderen Konfigurationen definiert werden müssen. Sie können sofort zum Filtern von Pipeline-Ausführungen verwendet werden (z. B. mit dataform run --tags ...).
bigQueryLabels array[map] Nein - Eine Liste von Schlüssel/Wert-Paaren, die BigQuery-Labels für die Zieltabelle darstellen (z. B. Schlüssel: data_class, Wert: transactional).
clusterDetails map Nein – Optional. Konfiguration für BigQuery-Clustering. Weitere Informationen finden Sie unter Details zum Clustering.
partitionDetails map Nein – Optional. Konfiguration der BigQuery-Partitionierung. Weitere Informationen finden Sie unter Partitionierungsdetails.

Stil des Datenprodukts

In einem Datenproduktmodul ist die Datei table_settings.yaml (ProductTableSettings-Block) als Dictionary (Map) unter den Stammschlüsseln ecc, s4 und common strukturiert. Die Schlüssel dieses Dictionarys stellen die Namen der analytischen Zieltabellen oder ‑ansichten dar (Groß-/Kleinschreibung wird nicht beachtet). Jeder Wert ist ein Product TableItem-Konfigurationsblock (ProductTableItem), in dem Materialisierungsstrategien, die Aktivierung von Tabellen und Leistungsoptimierungen definiert werden.

Beispiel für YAML-Syntax

common:
  currency_conversion:
    materializationType: table
    bigQueryLabels:
      - key: data_class
        value: transactional
      - key: line_of_business
        value: finance
    dataformTags: [sap, dataproduct, common]
    enabled: true
    retentionDays: 365 # Custom parameter passed to Dataform context
s4:
  customers:
    materializationType: incremental
    bigQueryLabels:
      - key: data_class
        value: master
    dataformTags: [sap, dataproduct, masterdata]
    enabled: true
    clusterDetails:
      columns: [mandt, ktokd]
    partitionDetails:
      column: erdat
      partitionType: time
      timeGrain: day

Parameterverweis

Parameter Typ Erforderlich Standard / Beispiel Beschreibung
ecc | s4 | common map Nein {} Eine Zuordnung von analytischen Ziel-Assets (Tabellen oder Ansichten) zu ihren ProductTableItem-Konfigurationsdeskriptoren.
[table_name] map Nein {} Der Schemablock Product Table Item, mit dem ein bestimmtes Analyse-Asset konfiguriert wird.
[table_name].enabled boolean Nein true Steuert, ob die Analysetabelle oder ‑ansicht ([table_name]) aktiv ist und beim Erstellen des Dataform-Arbeitsbereichs berücksichtigt wird.

• true (Standard): Die Tabellendefinition wird verarbeitet, mit table_config-Eigenschaften angereichert und in das Dataform-Ausgabeverzeichnis kopiert.

• false: Die Tabellendefinition wird während des Builds übersprungen (SapProductBuilder protokolliert und lässt sie aus). Die Tabelle oder Ansicht wird nicht kopiert oder in Dataform erstellt. Sie wird also effektiv von der Bereitstellung ausgeschlossen, ohne dass die Quelldefinitionsdateien gelöscht werden.
[table_name].materializationType string Nein incremental Wie das Analyse-Asset in BigQuery erstellt wird.

Zulässige Werte:

  • incremental (Standard): Es werden nur neue oder aktualisierte Datensätze seit dem letzten Lauf verarbeitet. Empfohlen für große transaktionale Datasets, um Kosten zu sparen.
  • table: Die Tabelle wird bei jeder Ausführung von Grund auf neu erstellt.
  • view: Das Asset wird als BigQuery-SQL-Ansicht (virtuelle Tabelle) bereitgestellt.
[table_name].dataformTags array[string] Nein [sap, dataproduct] Metadatentags, die an das Analyse-Asset in Dataform angehängt sind. Das sind beliebige Strings, die nicht vorab registriert werden müssen. Sie können sofort für selektive Pipeline-Ausführungen verwendet werden, z. B. mit dataform run --tags ....
[table_name].bigQueryLabels array[map] Nein - Eine Liste von Schlüssel/Wert-Paaren, die BigQuery-Labels für das Zielanalyse-Asset darstellen (z. B. Schlüssel: data_class, Wert: master).
[table_name].clusterDetails map Nein – Optional. Konfiguration für BigQuery-Clustering. Weitere Informationen finden Sie unter Details zum Clustering.
[table_name].partitionDetails map Nein – Optional. Konfiguration der BigQuery-Partitionierung. Weitere Informationen finden Sie unter Partitionierungsdetails.

Erweiterte BigQuery-Konfigurationen

Beide Stile haben dieselbe Struktur für die Optimierung von BigQuery-Speicher und Abfrageleistung durch Clustering und Partitionierung.

Details zum Clustering

Beim Clustering werden Daten anhand der Werte in bestimmten Spalten zusammengefasst. BigQuery sortiert die Daten in jedem Speicherblock anhand dieser Spalten. Dadurch werden Abfragen, die nach diesen Spalten filtern (WHERE) oder sie verknüpfen (JOIN), erheblich beschleunigt.

clusterDetails:
  columns: [bukrs, gjahr]
Parameterverweis
Parameter Typ Erforderlich Beispiel Beschreibung
columns array[string] Ja [bukrs, gjahr] Eine sortierte Liste mit bis zu vier Spaltennamen, nach denen die Tabelle geclustert werden soll.

Einschränkung:Spalten müssen alphanumerisch sein und dürfen nur Unterstriche enthalten. Die Reihenfolge der Spalten in der Liste bestimmt die Sortierhierarchie.

Details zur Partitionierung

Beim Partitionieren wird eine große Tabelle anhand der Werte einer Datums-, Zeitstempel- oder Ganzzahlspalte in kleinere physische Segmente unterteilt. So wird verhindert, dass BigQuery die gesamte Tabelle scannt, wenn in einer Abfrage nur ein bestimmter Bereich von Tagen, Monaten oder IDs angefordert wird.

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
Parameterverweis
Parameter Typ Erforderlich Beispiel Beschreibung
column string Ja budat Der Spaltenname, der zum Partitionieren der Tabelle verwendet wird. Darf nur alphanumerische Zeichen und Unterstriche enthalten. Der Spaltentyp muss mit partitionType übereinstimmen.
partitionType string Ja time Die Partitionierungsstrategie.

Zulässige Werte:

  • time: Partitioniert nach einer Zeiteinheit (Spalte „Datum“, „Zeitstempel“ oder „Datums-/Uhrzeitformat“).
  • DATE: Partitioniert explizit nach einer Datumsspalte.
  • integer: Partitioniert nach einem Ganzzahlbereich.
timeGrain string Nein day Erforderlich, wenn partitionType time oder DATE ist. Definiert die Granularität der Zeitpartitionen.

Zulässige Werte:hour, day, month, year (Groß-/Kleinschreibung wird nicht berücksichtigt).
rangeStart integer Nein 1 Erforderlich, wenn partitionType integer ist. Der Startwert der ersten Partition (einschließlich).
rangeEnd integer Nein 1000 Erforderlich, wenn partitionType integer ist. Der Endwert der letzten Partition (ausschließlich).
rangeInterval integer Nein 10 Erforderlich, wenn partitionType integer ist. Die Breite jedes Partitionsintervalls.

Beispiele

Die folgenden Beispiele zeigen Konfigurationsvorlagen für Datenfundament- und Datenproduktmodule. Sie veranschaulichen, wie Sie Zieltabellen anpassen, das Speicherlayout in BigQuery optimieren und Materialisierungstypen konfigurieren.

1. Beispiel für benutzerdefinierte Einstellungen für die Fundamentaldatentabelle

In diesem Beispiel wird gezeigt, wie Sie eine Fundierungsebene mit geclusterten und partitionierten Transaktionstabellen (z. B. bseg und ekbe) neben Standarddatentabellen konfigurieren:

# ==============================================================================
# S/4HANA-Specific Tables
# ==============================================================================
s4:
  # ACDOCA is a massive table in S/4HANA; clustering is vital
  - source:
      tableName: acdoca
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, s4, finance, transactional, hourly]
      clusterDetails:
        columns: [rclnt, rbukrs, gjahr]

# ==============================================================================
# ECC-Specific Tables
# ==============================================================================
ecc:
  - source:
      tableName: faglflexa
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, ecc, finance, transactional, hourly]

# ==============================================================================
# Common Tables (ECC & S/4HANA)
# ==============================================================================
common:
  # Financial document header (partitioned by posting date)
  - source:
      tableName: bkpf
      isCdc: true
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day

  # Purchasing document items (partitioned by creation date)
  - source:
      tableName: ekpo
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, common, logistics, purchasing, hourly]
      clusterDetails:
        columns: [mandt, ebeln]
      partitionDetails:
        column: aedat
        partitionType: time
        timeGrain: month

  # Standard master data table (no partitioning/clustering needed)
  - source:
      tableName: lfa1
    target:
      bigQueryLabels:
        - key: data_class
          value: master
      dataformTags: [sap, common, masterdata, vendor, daily]

2. Beispiel für benutzerdefinierte Einstellungen für die Tabelle mit Datenprodukten

In diesem Beispiel wird gezeigt, wie Sie Materialisierungstypen für nachgelagerte analytische Datenprodukte konfigurieren. Wir legen transaktionale sales_documents als inkrementell fest, um die Build-Leistung zu optimieren und Kosten zu sparen. Nicht transaktionale Datentabellen wie customers werden als Standardtabellen erstellt:

# settings applied for both ECC and S/4HANA pipelines
common:
  # Transactional data product - incremental build
  sales_documents:
    materializationType: incremental
    bigQueryLabels:
      - key: data_class
        value: transactional
    dataformTags: [sap, dataproduct, sales, transactional]
    clusterDetails:
      columns: [vkorg, vbeln]
    partitionDetails:
      column: audat
      partitionType: time
      timeGrain: day

  # Master data product - full table rebuild
  customers:
    materializationType: table
    bigQueryLabels:
      - key: data_class
        value: master
    dataformTags: [sap, dataproduct, masterdata]
    clusterDetails:
      columns: [mandt, ktokd]

  # Aggregated reporting view - virtual view
  sales_performance_summary:
    materializationType: view
    bigQueryLabels:
      - key: data_class
        value: transactional
    dataformTags: [sap, dataproduct, sales, reporting]

Anleitungen

In diesem Abschnitt finden Sie detaillierte Anleitungen für gängige Konfigurationsaufgaben und benutzerdefinierte Bereitstellungsszenarien.

Tabellenbereich in einem Datenfundierungsmodul anpassen

So fügen Sie einem vorhandenen Data Foundation-Modul Tabellen hinzu oder entfernen sie daraus, ohne neue Module zu erstellen oder separate Pipeline-Instanzen auszuführen:

  • Kopieren Sie die Standardkonfigurationen für table_settings.default.yaml in das Konfigurationsverzeichnis Ihres Arbeitsbereichs (z. B. config/cortex/sap/foundations/sap/custom_table_settings.yaml).
  • Fügen Sie in der neuen Datei nach Bedarf benutzerdefinierte Tabellen unter den Schlüsseln ecc, s4 oder common hinzu oder entfernen Sie nicht verwendete Standardtabellen:
common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]
  • Aktualisieren Sie config/config.yaml, damit auf den Pfad der benutzerdefinierten Tabelleneinstellungen in der tableSettings-Eigenschaft des Moduls verwiesen wird:
data:
  modules:
    foundations:
      - moduleId: erp
        modulePath: cortex.sap.foundations.sap
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
        tableSettings: 'cortex/sap/foundations/sap/custom_table_settings.yaml'
  • Wenn Sie das Tabellenschema der zusätzlichen Tabelle mit Anmerkungen (Tabellen- und Spaltenbeschreibungen) anreichern möchten, erstellen Sie eine Anmerkungsdatei im Namespace des verwendeten Data Foundation-Moduls. In diesem Beispiel ist der Pfad zum Speichern der Annotationsdatei custom_table_name.yaml basierend auf modulePath: cortex.sap.foundations.sap src/data_modules/cortex/sap/foundations/sap/annotations. Das Format der Anmerkungsdateien wird im Leitfaden zur Erweiterbarkeit für Data Foundation beschrieben.

Mehrere Instanzen eines Data Foundation-Moduls konfigurieren

Sie möchten zwei oder mehr separate Pipeline-Instanzen desselben Modultyps bereitstellen, z. B. zur Unterstützung mehrerer SAP-Instanzen, zum Segmentieren von Tabellen, zum Isolieren von Umgebungen oder zum Ausrichten auf verschiedene Zieldatasets.

Hinweis:

  • Prüfen Sie, ob die Quelltabellen in Ihrem Quell-Rohdataset vorhanden sind.
  • Prüfen Sie beim Arbeiten mit SAP Data Foundation-Modulen, ob die Metadatentabelle DD03L Spalten und Deskriptorinformationen für die benutzerdefinierten Tabellen enthält, die Sie aufnehmen möchten. Weitere Informationen finden Sie unter SAP ERP-Anforderungen.

Anleitung:

  • Fügen Sie in der Datei config/config.yaml unter data.targets Zielkonfigurationen hinzu, um Zieldatasets für jede Pipeline-Instanz zu definieren:
data:
  targets:
    - id: data_foundation_core
      projectId: target_project_id
      datasetId: data_foundation_sap_core
    - id: data_foundation_custom
      projectId: target_project_id
      datasetId: data_foundation_sap_custom
  • Definieren Sie mehrere Instanzen des Moduls in der Liste data.modules.foundations. Geben Sie für jede Instanz eine eindeutige moduleId, eigene Ziel-Dataset-IDs und optional eine tableSettings-Konfiguration an:
data:
  modules:
    foundations:
      # Core SAP ERP foundation module instance
      - moduleId: erp_core
        modulePath: cortex.sap.foundations.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_core
        # If omitted, defaults to "../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml"
        # tableSettings: "../src/data_modules/cortex/sap/foundations/sap/table_settings.default.yaml"
      # Custom tables pipeline instance
      - moduleId: erp_custom
        modulePath: cortex.sap.foundations.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_custom
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
        tableSettings: "cortex/sap/foundations/sap/custom_datafoundation_table_settings.yaml"
  • Erstellen Sie die config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml-Datei, in der der benutzerdefinierte Bereich angegeben wird. Beispiel:
common:
  - source:
      tableName: custom_sap_table_name
    target:
      dataformTags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day

  • Wenn Sie das Tabellenschema der zusätzlichen Tabelle mit Anmerkungen (Tabellen- und Spaltenbeschreibungen) anreichern möchten, erstellen Sie eine Anmerkungsdatei im Namespace des verwendeten Data Foundation-Moduls. In diesem Beispiel ist der Pfad zum Speichern der Annotationsdatei custom_table_name.yaml basierend auf modulePath: cortex.sap.foundations.sap src/data_modules/cortex/sap/foundations/sap/annotations. Das Format der Anmerkungsdateien wird im Leitfaden zur Erweiterbarkeit für Data Foundation beschrieben.

  • Wenden Sie die Änderungen an, indem Sie das Bereitstellungsskript (uv run cortex-build-and-deploy) ausführen. Führen Sie dann die Dataform-Aktionen aus, wie unter Schritte nach der Bereitstellung beschrieben.