Configurazione del deployment

Questa pagina spiega le opzioni di configurazione del deployment per Cortex Framework nelle seguenti aree:

Questa pagina fornisce anche guide pratiche con istruzioni passo passo per casi d'uso e scenari di deployment comuni.

File di configurazione: config/config.yaml

Il file config/config.yaml, in genere inizializzato dal modello config/config.yaml.example, funge da configurazione principale per il deployment di Cortex Framework. La configurazione è suddivisa nei seguenti blocchi strutturali:

  1. Ambiente di build (buildEnvironment): gestisce il livello di orchestrazione della build, specificando il progetto Google Cloud centrale in cui vengono fatturati ed eseguiti i calcoli dei metadati intermedi, le convalide del database e le ricerche dello schema.
  2. Dati (data): regola l'architettura logica dei dati. Questo blocco configura le posizioni dei set di dati, i limiti degli spazi dei nomi, i dettagli di connessione per le origini di importazione non elaborata, i set di dati di destinazione e registra le istanze dei moduli di dati (foundations, catalogs e products).
  3. Deployment (deployment): configura i deployment del sistema di destinazione fisico. Specifica i dettagli del repository Dataform (ID progetto, posizione, nome del repository e workspace di sviluppo) in cui vengono implementate le pipeline di trasformazione SQLX/JS compilate.

Le sezioni seguenti forniscono una suddivisione dettagliata di ciascun blocco.

Ambiente di build

Il progetto dell'ambiente di build è il progetto a cui vengono addebitate le azioni di build, come i job BigQuery che leggono DD03L.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

La seguente tabella descrive i parametri dell'ambiente di build.

Parametro Significato Valore predefinito Descrizione
buildEnvironment.buildProjectId ID progetto build YOUR_BUILD_PROJECT_ID Google Cloud ID progetto in cui vengono eseguite le operazioni di build.

Panoramica della sezione Dati

La sezione data: del file di configurazione definisce le origini dati, i target e i moduli specifici per la base di dati e i prodotti di dati. La sua struttura generale è la seguente:

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:
    - ...

Dati: posizione BigQuery

Definisce la posizione dei set di dati di origine e di destinazione BigQuery.

Parametro Significato Valore predefinito Descrizione
data.bigQueryLocation Località BigQuery US Posizione del set di dati BigQuery (ad esempio US, us-central1 o europe-west1).

Dati: spazio dei nomi Cortex

Definisce lo spazio dei nomi di Cortex Framework.

Parametro Significato Valore predefinito Descrizione
data.namespaces.name Nome dello spazio dei nomi - Nome dello spazio dei nomi di Cortex Framework. Ad esempio, cortex.
data.namespaces.path Percorso dello spazio dei nomi - Percorso dello spazio dei nomi di Cortex Framework per le sottodirectory utilizzate all'interno delle cartelle src e config. Ad esempio, cortex.

Dati: origini BigQuery e set di dati di destinazione

L'elenco dei set di dati definisce i punti di connessione dei dati non elaborati in entrata e le posizioni di archiviazione in uscita per il framework. Ogni set di dati registra un identificatore univoco mappato a un progetto Google Cloud e a un set di dati BigQuery specifici.

I set di dati vengono referenziati dai moduli utilizzando il loro ID univoco.

# 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

La seguente tabella descrive i parametri di mappatura del set di dati.

Parametro Significato Valore predefinito Descrizione
data.datasets.id ID set di dati - Definisce un identificatore univoco per il set di dati (ad es. sap_raw o sap_foundation).
data.datasets.projectId ID progetto - Fa riferimento all'ID progetto Google Cloud che ospita il set di dati.
data.datasets.datasetId ID set di dati BigQuery - Fa riferimento al nome effettivo del set di dati BigQuery.

Dati: moduli

I moduli definiscono la struttura e i componenti delle pipeline di dati Dataform.

Dati: Moduli: Elementi di base

Questa sezione configura i moduli del livello di base dei dati che elaborano i dati dal livello non elaborato in una rappresentazione standardizzata dei record più recenti dei dati di origine. Se l'origine fornisce direttamente una visualizzazione degli ultimi record o se queste trasformazioni vengono eseguite dal connettore del sistema di origine, il modulo può essere configurato come origine esterna della base dati.

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"

La tabella seguente descrive i parametri dei moduli di base dei dati per la configurazione di modules.foundations.

Parametro Significato Valore predefinito Descrizione
moduleId Identificatore modulo erp Identificatore univoco di un'istanza specifica del modulo di trasformazione della base di dati.
modulePath Percorso del modulo cortex.sap.foundations.sap Definisce il percorso con spazio dei nomi del modulo, della logica di business o del modello applicato. Formato: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap} (ad esempio, cortex.sap.foundations.sap).
dataSourceId Link origine sap_raw Fa riferimento all 'ID dell'elenco data.datasets da cui estrarre i dati.
dataTargetId Link di destinazione sap_foundation Fa riferimento all 'ID dell'elenco data.datasets a cui inviare i dati.
moduleSettings.sapVersion Versione del sistema SAP ecc Valido solo per le origini dati SAP. Determina la logica specifica dell'origine per i sistemi ecc (ECC) o s4 (S/4HANA).
moduleSettings.mandt SAP Client (Mandant) 100 Valido solo per le origini dati SAP. L'identificatore client SAP di tre cifre utilizzato per filtrare le righe di dati.
enabled Attivazione del modulo true Specifica se il modulo è abilitato.
external Fondazione esterna false Specifica se la base è esterna (non crea il set di dati di destinazione).
tableSettings Impostazioni della tabella src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml Percorso del file di configurazione delle impostazioni della tabella personalizzate, relativo a questo file di configurazione.
Percorso consigliato: relativo alla directory `config/`: "{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml"
Percorso predefinito: "../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml"

Dati: Moduli: Cataloghi

I cataloghi lakehouse esterni consentono a Cortex Framework di importare tabelle esterne da cataloghi e condivisioni BigLake Delta Sharing senza manifest fisici.

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

La seguente tabella descrive i parametri di configurazione del catalogo esterno.

Parametro Significato Valore predefinito Descrizione
id Identificatore catalogo - Identificatore univoco di un'istanza specifica del modulo del catalogo esterno.
type Tipo di catalogo lakehouse_delta_share Il tipo di catalogo. Supporta lakehouse_delta_share.
bindsNamespaces Spazi dei nomi associati - Un elenco di prefissi di spazi dei nomi logici associati a questo catalogo (ad es. [sap_bdc]).
connectionSettings.catalogId ID catalogo fisico - ID catalogo fisico. In genere uguale all'ID modulo.
connectionSettings.projectId ID progetto - L'ID progetto Google Cloud in cui viene gestita la connessione al catalogo.
connectionSettings.location Località - La posizione della regione geografica per il catalogo.
connectionSettings.shares Condivisioni - Elenco delle condivisioni Delta Sharing da importare. Ogni condivisione deve contenere un shareId.
enabled Abilitazione del catalogo true Specifica se il catalogo è abilitato.

Dati: Moduli: Prodotti

I moduli dei prodotti di dati definiscono le aggregazioni, i calcoli e le unioni necessari per trasformare i dati non elaborati in approfondimenti che soddisfano casi d'uso aziendali specifici.

La configurazione dei prodotti di dati consente di impostare l'ID univoco, la definizione delle dipendenze, nonché il riferimento al modulo di base dei dati e al set di dati di destinazione in cui verranno archiviati i risultati.

La configurazione dettagliata dei prodotti dati specifici è definita all'interno dei file a cui fa riferimento la chiave: tableSettings.

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"

La seguente tabella descrive i parametri dei moduli del prodotto di dati per la configurazione di modules.products.

Parametro Significato Valore predefinito Descrizione
moduleId Identificatore modulo - Identificatore univoco di un'istanza specifica del modulo di trasformazione.
modulePath Percorso del modulo - Definisce il percorso con spazio dei nomi del modulo, della logica di business o del modello applicato, formato: {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}, ad esempio cortex.sap.products.purchasing_organizational_structure, definito nella cartella src/data_modules/{namespace_dir}/{system_type}/products/{product_name}.
dataTargetId Link di destinazione product_target Fa riferimento all 'ID dell'elenco delle destinazioni a cui inviare i dati.
dependencyBindings Dipendenza upstream sapModule: erp Specifica i mapping per soddisfare le dipendenze dei moduli. Ad esempio, la mappatura di sapModule a erp.
enabled Attivazione del modulo true Specifica se il modulo è abilitato.
syncToKc Sincronizzazione di Knowledge Catalog true Indica se questo prodotto di dati è sincronizzato con Knowledge Catalog.
tableSettings Impostazioni della tabella src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml Percorso del file di configurazione delle impostazioni della tabella personalizzate, relativo a questo file di configurazione.
Percorso consigliato: relativo alla directory `config/`: "{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml"
Percorso predefinito: "../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml"

Ambiente di deployment

Cortex Framework utilizza Dataform per orchestrare le trasformazioni SQL in BigQuery. Il blocco deployment: definisce la configurazione di Dataform, responsabile dell'esecuzione delle pipeline di dati, inclusi il progetto del repository, la posizione, il nome del repository e il nome dello spazio di lavoro Dataform.

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

La seguente tabella descrive i parametri di località delle destinazioni di deployment (deployment.targets:).

Parametro Significato Valore predefinito Descrizione
type Tipo di deployment dataform Il tipo di destinazioni di deployment.
enabled Attivato/ Disattivato true Specifica se la destinazione di deployment specificata è abilitata o disabilitata.
targetSettings.repositoryProjectId ID progetto repository YOUR_REPO_PROJECT_ID L'ID progetto Google Cloud in cui viene gestito il repository Dataform.
targetSettings.repositoryRegion Regione del repository us-central1 La regione Google Cloud per il repository Dataform (ad esempio us-central1 o europe-west1).
targetSettings.repositoryName Nome repository cortex-repository Il nome specifico del repository Dataform.
targetSettings.workspaceName Nome workspace dev L'area di lavoro Dataform specifica utilizzata per il ciclo di deployment.
targetSettings.serviceAccount Email dell'account di servizio - Email del account di servizio predefinito per l'esecuzione del repository Dataform.

File di configurazione: table_settings.yaml

Questa guida spiega come utilizzare il file table_settings.yaml per configurare le tabelle di base dei dati e dei prodotti di dati in Google Cloud Cortex Framework.

Il file table_settings.yaml specifico del modulo di dati controlla la conformità delle tabelle di origine non elaborate e la materializzazione dei modelli di dati analitici in BigQuery. Utilizzando questo file, puoi configurare tag, strategie di materializzazione e funzionalità avanzate di BigQuery per il rendimento, come il partizionamento o il clustering.

Risoluzione dinamica delle dipendenze

Per impostazione predefinita, Cortex Framework ottimizza l'impronta di deployment e il tempo di esecuzione eseguendo il deployment e la compilazione solo delle tabelle di base richieste come dipendenze dei prodotti di dati abilitati. Se una tabella configurata in table_settings.yaml non ha prodotti di dati downstream attivi che dipendono da essa, viene omessa dalla distribuzione.

Per ignorare questa ottimizzazione e forzare il deployment di una tabella di base, puoi impostare l'attributo deployAlways su true (vedi Riferimento al parametro di stile della base dati).

In Google Cloud Cortex Framework, a ogni modulo (di base o di prodotto) può essere assegnato un file di impostazioni della tabella specifico nel file di configurazione della distribuzione: config/config.yaml utilizzando la proprietà tableSettings.

Percorsi di configurazione

  • Impostazioni personalizzate (consigliate): per personalizzare i comportamenti della tabella, copia il file predefinito nella directory di configurazione, modificalo e fai riferimento al relativo percorso in config/config.yaml. I percorsi consigliati da utilizzare (relativi alla directory config/) sono:
    • Moduli di base: namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml (ad es. config/cortex/sap/foundations/sap/table_settings.yaml)
    • Moduli del prodotto: namespace_dir/system_type/products/product_name/custom_table_settings.yaml (ad es. config/cortex/sap/products/accounting_documents/table_settings.yaml)
  • Fallback predefinito:se tableSettings viene omesso, il framework esegue automaticamente il fallback a:
    • Moduli di base: ../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
    • Moduli del prodotto: ../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

Stili di configurazione

Esistono due stili di schema distinti per table_settings.yaml a seconda della categoria del modulo:

  1. Stile Data Foundation: mappatura basata su elenchi che definisce le relazioni tra schemi di origine e di destinazione, la gestione CDC (Change Data Capture) e il layout BigQuery. Tieni presente che il layout delle impostazioni della tabella di base dei dati è specifico del sistema di origine.

  2. Stile prodotto di dati:mappatura basata su mappe (dizionario) che definisce come vengono materializzate e ottimizzate le visualizzazioni o le tabelle analitiche (ad es. come visualizzazioni, tabelle o tabelle incrementali).

Entrambi gli stili supportano tre sezioni di primo livello per separare le configurazioni in base alla versione del sistema di origine (utilizzate principalmente per SAP Data Foundation e i prodotti dipendenti da SAP):

  • ecc: impostazioni applicate solo durante il deployment di un sistema di origine SAP ECC.
  • s4: Impostazioni applicate solo durante il deployment di un sistema di origine SAP S/4HANA.
  • common: impostazioni applicate indipendentemente dalla versione di SAP (utilizzate per le impostazioni conformi o universali).

Stile delle basi di dati per SAP ERP

In un modulo delle basi di dati per i sistemi di origine SAP ERP, il file table_settings.yaml è strutturato come un elenco di elementi della tabella nelle chiavi ecc, s4 e common. Ogni elemento mappa una tabella di origine non elaborata a una tabella di destinazione conforme e configura le relative impostazioni BigQuery.

Esempio di sintassi YAML

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

Riferimento ai parametri

Parametro Tipo Obbligatorio Predefinito / Esempio Descrizione
[].source object Sì [] Descrive la tabella nel sistema di origine in entrata della base dati (ad es. `sap_raw`). Vedi le impostazioni dell'origine.
[].target object Sì [] Descrive la tabella di destinazione nei set di dati di base (ad es. `sap_data_foundation`). Consulta le impostazioni di destinazione.
ecc | s4 | common string No [] Versione o dialetto del sistema di origine.
[].deployAlways boolean No false Se true, la tabella viene sempre implementata e creata, anche se le regole di ottimizzazione potrebbero altrimenti ignorarla. Vedi anche Risoluzione dinamica delle dipendenze
Impostazioni fonti

Definisce le caratteristiche della tabella di importazione non elaborata.

Parametro Tipo Obbligatorio Predefinito / Esempio Descrizione
tableName string Sì - Il nome della tabella di origine non elaborata in BigQuery (senza distinzione tra maiuscole e minuscole) così come viene importata dal connettore dal sistema di origine .
sapTableName string No - Il nome della tabella SAP (senza distinzione tra maiuscole e minuscole) come definito nelle tabelle dei metadati del sistema di origine (ad es. `DD03L`). Se definito, questo parametro viene utilizzato come nome per la tabella della base dati corrispondente.
isCdc boolean No true Indica se la tabella di origine contiene log Change Data Capture (CDC).

• true (impostazione predefinita): il framework elabora i log CDC (utilizzando i timestamp dei record e i flag di operazione) per ricostruire l'ultimo stato conforme.

• false: la tabella viene elaborata come uno snapshot completo.
Impostazioni di targeting

Definisce il layout della tabella convalidata di output nel set di dati di destinazione.

Parametro Tipo Obbligatorio Predefinito / Esempio Descrizione
tableName string No *(Come la fonte)* Il nome della tabella di destinazione conforme da creare. Se omesso, il framework utilizza per impostazione predefinita l'origine tableName.
dataformTags array[string] No [sap, finance] Un elenco di tag di metadati collegati all'azione standardizzata in Dataform. Queste sono stringhe arbitrarie e non devono essere preregistrate o definite in altre configurazioni. Possono essere utilizzate immediatamente per filtrare le esecuzioni della pipeline (ad esempio, utilizzando dataform run --tags ...).
bigQueryLabels array[map] No - Un elenco di coppie chiave-valore che rappresentano le etichette BigQuery da applicare alla tabella di destinazione (ad esempio, chiave: data_class, valore: transactional).
clusterDetails map No — Facoltativo. Configurazione del clustering BigQuery. Consulta Dettagli del clustering.
partitionDetails map No — Facoltativo. Configurazione del partizionamento BigQuery. Consulta i dettagli del partizionamento.

Stile del prodotto di dati

In un modulo del prodotto di dati, il file table_settings.yaml (blocco ProductTableSettings) è strutturato come un dizionario (mappa) nelle chiavi radice ecc, s4 e common. Le chiavi di questo dizionario rappresentano i nomi delle tabelle o delle viste analitiche di destinazione (senza distinzione tra maiuscole e minuscole) e ogni valore è un blocco di configurazione Product TableItem (ProductTableItem) che definisce le strategie di materializzazione, l'attivazione delle tabelle e le ottimizzazioni del rendimento.

Esempio di sintassi YAML

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

Riferimento ai parametri

Parametro Tipo Obbligatorio Predefinito / Esempio Descrizione
ecc | s4 | common map No {} Una mappa degli asset analitici di destinazione (tabelle o viste) ai relativi descrittori di configurazione ProductTableItem.
[table_name] map No {} Il blocco dello schema del descrittore Elemento tabella prodotto che configura una risorsa analitica specifica.
[table_name].enabled boolean No true Controlla se la tabella o la vista analitica ([table_name]) è attiva e inclusa durante la creazione dello spazio di lavoro Dataform.

• true (impostazione predefinita): la definizione della tabella viene elaborata, arricchita con le proprietà table_config e copiata nella directory di output di Dataform.

• false: la definizione della tabella viene ignorata durante la build (SapProductBuilder registra e omette). La tabella o la vista non verranno copiate o integrate in Dataform, il che le esclude di fatto dal deployment senza eliminare i file di definizione dell'origine.
[table_name].materializationType string No incremental Come viene creato l'asset analitico in BigQuery.

Valori consentiti:

  • incremental (impostazione predefinita): elabora solo i record nuovi o aggiornati dall'ultima esecuzione. Consigliato per set di dati transazionali di grandi dimensioni per risparmiare sui costi.
  • table: ricostruisce completamente la tabella da zero a ogni esecuzione.
  • view: esegue il deployment dell'asset come vista SQL BigQuery (tabella virtuale).
[table_name].dataformTags array[string] No [sap, dataproduct] Tag dei metadati collegati all'asset analitico in Dataform. Si tratta di stringhe arbitrarie e non devono essere preregistrate; possono essere utilizzate immediatamente per esecuzioni selettive della pipeline (ad esempio, utilizzando dataform run --tags ...).
[table_name].bigQueryLabels array[map] No - Un elenco di coppie chiave-valore che rappresentano le etichette BigQuery da applicare all'asset analitico di destinazione (ad esempio, chiave: data_class, valore: master).
[table_name].clusterDetails map No — Facoltativo. Configurazione del clustering BigQuery. Consulta Dettagli del clustering.
[table_name].partitionDetails map No — Facoltativo. Configurazione del partizionamento BigQuery. Consulta i dettagli del partizionamento.

Configurazioni avanzate di BigQuery

Entrambi gli stili condividono la stessa struttura per ottimizzare l'archiviazione e le prestazioni delle query BigQuery tramite clustering e partizionamento.

Dettagli del clustering

Il clustering colloca i dati in base ai valori di colonne specifiche. BigQuery ordina i dati all'interno di ogni blocco di archiviazione utilizzando queste colonne, il che velocizza notevolmente le query che filtrano (WHERE) o uniscono (JOIN) i dati.

clusterDetails:
  columns: [bukrs, gjahr]
Riferimento ai parametri
Parametro Tipo Obbligatorio Esempio Descrizione
columns array[string] Sì [bukrs, gjahr] Un elenco ordinato di massimo quattro nomi di colonne in base ai quali raggruppare la tabella.

Vincolo:le colonne devono essere alfanumeriche e contenere solo trattini bassi. L'ordine delle colonne nell'elenco determina la gerarchia di ordinamento.

Dettagli partizionamento

Il partizionamento divide una tabella di grandi dimensioni in segmenti fisici più piccoli in base ai valori di una colonna di data, timestamp o numeri interi. In questo modo, BigQuery non esegue la scansione dell'intera tabella quando una query richiede solo un intervallo specifico di giorni, mesi o ID.

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
Riferimento ai parametri
Parametro Tipo Obbligatorio Esempio Descrizione
column string Sì budat Il nome della colonna utilizzata per partizionare la tabella. Deve essere composto solo da caratteri alfanumerici e trattini bassi. Il tipo di colonna deve corrispondere a partitionType.
partitionType string Sì time La strategia di partizionamento.

Valori consentiti:

  • time: partizioni per unità di tempo (colonna Data, Timestamp o Datetime).
  • DATE: Partizioni esplicitamente per una colonna Data.
  • integer: Partizioni per intervallo di numeri interi.
timeGrain string No day Obbligatorio se partitionType è time o DATE. Definisce la granularità delle partizioni temporali.

Valori consentiti: hour, day, month, year (senza distinzione tra maiuscole e minuscole).
rangeStart integer No 1 Obbligatorio se partitionType è integer. Il valore iniziale della prima partizione (inclusa).
rangeEnd integer No 1000 Obbligatorio se partitionType è integer. Il valore di fine dell'ultima partizione (escluso).
rangeInterval integer No 10 Obbligatorio se partitionType è integer. La larghezza di ogni intervallo di partizione.

Esempi

Gli esempi seguenti mostrano i modelli di configurazione per i moduli di base dei dati e del prodotto di dati, illustrando come personalizzare le tabelle di destinazione, ottimizzare il layout di archiviazione in BigQuery e configurare i tipi di materializzazione.

1. Esempio di impostazioni della tabella di base di dati personalizzati

Questo esempio mostra come configurare un livello di base con tabelle transazionali in cluster e partizionate (come bseg e ekbe) insieme a tabelle di dati standard:

# ==============================================================================
# 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. Esempio di impostazioni della tabella dei prodotti di dati personalizzati

Questo esempio mostra come configurare i tipi di materializzazione per i prodotti di dati analitici downstream. Impostiamo sales_documents transazionali come incrementali per ottimizzare le prestazioni di compilazione e risparmiare sui costi, mentre le tabelle di dati non transazionali come customers vengono create come tabelle standard:

# 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]

Guide illustrative

Questa sezione fornisce guide passo passo per le attività di configurazione comuni e gli scenari di deployment personalizzati.

Personalizzare l'ambito della tabella in un modulo della base dati

Per aggiungere o rimuovere tabelle all'interno di un modulo di base dati esistente senza creare nuovi moduli o eseguire istanze di pipeline separate:

  • Copia le configurazioni table_settings.default.yaml predefinite nella directory di configurazione del workspace (ad esempio, config/cortex/sap/foundations/sap/custom_table_settings.yaml).
  • Nel nuovo file, aggiungi le tabelle personalizzate o rimuovi le tabelle standard inutilizzate nelle chiavi ecc, s4 o common in base alle esigenze:
common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]
  • Aggiorna config/config.yaml in modo che faccia riferimento al percorso delle impostazioni della tabella personalizzata nella proprietà tableSettings del modulo:
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'
  • Per arricchire lo schema della tabella aggiuntiva con annotazioni (descrizioni di tabelle e colonne), crea un file di annotazioni nello spazio dei nomi del modulo di base dei dati che stai utilizzando. In questo esempio, in base a modulePath: cortex.sap.foundations.sap, il percorso in cui archiviare il file di annotazioni custom_table_name.yaml è src/data_modules/cortex/sap/foundations/sap/annotations. Il formato dei file di annotazione è descritto nella guida all'estensibilità per la base dati.

Configurare più istanze di un modulo della base di dati

Per eseguire il deployment di due o più istanze di pipeline separate dello stesso tipo di modulo (ad esempio, per supportare più istanze SAP, segmentare le tabelle, isolare gli ambienti o scegliere come target set di dati diversi).

Prima di iniziare:

  • Assicurati che le tabelle di origine esistano nel set di dati non elaborati di origine.
  • Quando lavori con i moduli SAP Data Foundation, verifica che la tabella dei metadati DD03L contenga colonne e informazioni sui descrittori per le tabelle personalizzate che intendi importare. Per maggiori dettagli, vedi Requisiti di SAP ERP.

Istruzioni:

  • Nel file config/config.yaml, aggiungi le configurazioni di destinazione in data.targets per definire i set di dati di destinazione per ogni istanza della pipeline:
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
  • Definisci più istanze del modulo nell'elenco data.modules.foundations. Assegna a ogni istanza un moduleId univoco, i propri ID set di dati di destinazione e, facoltativamente, la configurazione tableSettings:
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"
  • Crea il file config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml specificando l'ambito personalizzato. E.g.:
common:
  - source:
      tableName: custom_sap_table_name
    target:
      dataformTags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day

  • Per arricchire lo schema della tabella aggiuntiva con annotazioni (descrizioni di tabelle e colonne), crea un file di annotazioni nello spazio dei nomi del modulo di base dei dati che stai utilizzando. In questo esempio, in base a modulePath: cortex.sap.foundations.sap, il percorso in cui archiviare il file di annotazioni custom_table_name.yaml è src/data_modules/cortex/sap/foundations/sap/annotations. Il formato dei file di annotazione è descritto nella guida all'estensibilità per la base dati.

  • Applica le modifiche eseguendo lo script di deployment (uv run cortex-build-and-deploy), quindi esegui le azioni Dataform come descritto in Passaggi post-deployment.