Configuration du déploiement

Cette page décrit les options de configuration du déploiement pour le Cortex Framework dans les domaines suivants :

Cette page fournit également des guides pratiques contenant des instructions détaillées pour les cas d'utilisation et les scénarios de déploiement courants.

Fichier de configuration : config/config.yaml

Le fichier config/config.yaml, généralement initialisé à partir du modèle config/config.yaml.example, sert de configuration principale pour le déploiement du Cortex Framework. La configuration est divisée en blocs structurels :

  1. Environnement de compilation (buildEnvironment) : régit la couche d'orchestration de compilation, en spécifiant le projet Google Cloud central où la facturation et l'exécution des calculs de métadonnées intermédiaires, des validations de base de données et des recherches de schéma ont lieu.
  2. Données (data) : régit l'architecture logique des données. Ce bloc configure les emplacements des ensembles de données, les limites des espaces de noms, les informations de connexion pour les sources d'ingestion brutes et les ensembles de données de destination. Il enregistre également les instances de module de données (foundations, catalogs et products).
  3. Déploiement (deployment) : configure les déploiements du système cible physique. Il spécifie les détails du dépôt Dataform (ID de projet, emplacement, nom du dépôt et espace de travail de développement) où les pipelines de transformation SQLX/JS compilés sont déployés.

Les sections suivantes fournissent une description détaillée de chaque bloc.

Environnement de compilation

Le projet d'environnement de compilation est celui qui est facturé pour les actions de compilation, telles que les jobs BigQuery lisant DD03L.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

Le tableau suivant décrit les paramètres de l'environnement de compilation.

Paramètre Signification Valeur par défaut Description
buildEnvironment.buildProjectId ID du projet de compilation YOUR_BUILD_PROJECT_ID Google Cloud  : ID du projet dans lequel les opérations de compilation sont exécutées.

Présentation de la section "Données"

La section data: du fichier de configuration définit vos sources de données, vos cibles et les modules spécifiques pour la base de données et les produits de données. Sa structure générale est la suivante :

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

Données : emplacement BigQuery

Définit l'emplacement des ensembles de données BigQuery sources et cibles.

Paramètre Signification Valeur par défaut Description
data.bigQueryLocation Emplacement BigQuery US Emplacement de l'ensemble de données BigQuery (par exemple, US, us-central1 ou europe-west1).

Données : espace de noms Cortex

Définit l'espace de noms Cortex Framework.

Paramètre Signification Valeur par défaut Description
data.namespaces.name Nom de l'espace de noms - Nom de l'espace de noms Cortex Framework. Par exemple, cortex.
data.namespaces.path Chemin d'accès à l'espace de noms - Chemin d'espace de noms du Cortex Framework pour les sous-répertoires utilisés dans les dossiers src et config. Par exemple, cortex.

Données : sources BigQuery et ensembles de données cibles

La liste des ensembles de données définit les points de connexion des données brutes entrantes et les emplacements de stockage sortants pour le framework. Chaque ensemble de données enregistre un identifiant unique mappé à un projet Google Cloud et à un ensemble de données BigQuery spécifiques.

Les ensembles de données sont référencés à partir des modules à l'aide de leur ID unique.

# 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

Le tableau suivant décrit les paramètres de mappage des ensembles de données.

Paramètre Signification Valeur par défaut Description
data.datasets.id ID de l'ensemble de données - Définit un identifiant unique pour l'ensemble de données (par exemple, sap_raw ou sap_foundation).
data.datasets.projectId ID du projet - Fait référence à l'ID du projet Google Cloud qui héberge l'ensemble de données.
data.datasets.datasetId ID de l'ensemble de données BigQuery - Fait référence au nom réel de l'ensemble de données BigQuery.

Données : modules

Les modules définissent la structure et les composants des pipelines de données Dataform.

Données : Modules : Principes de base

Cette section configure les modules de la couche de base de données qui traitent les données de la couche brute pour obtenir une représentation standardisée des derniers enregistrements des données sources. Si la source fournit directement une vue sur les derniers enregistrements ou si de telles transformations sont effectuées par le connecteur du système source, le module peut être configuré comme source de data foundation externe.

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"

Le tableau suivant décrit les paramètres des modules de fondation de données pour la configuration modules.foundations.

Paramètre Signification Valeur par défaut Description
moduleId Identifiant du module erp Identifiant unique d'une instance de module de transformation de la base de données.
modulePath Chemin d'accès au module cortex.sap.foundations.sap Définit le chemin d'accès avec espace de noms au module, à la logique métier ou au modèle appliqué. Format : {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap} (par exemple, cortex.sap.foundations.sap).
dataSourceId Lien source sap_raw Fait référence à l'ID de la liste data.datasets à partir de laquelle extraire les données.
dataTargetId Lien cible sap_foundation Fait référence à l'ID de la liste data.datasets vers laquelle transférer les données.
moduleSettings.sapVersion Version du système SAP ecc Applicable uniquement aux sources de données SAP. Détermine la logique spécifique à la source pour les systèmes ecc (ECC) ou s4 (S/4HANA).
moduleSettings.mandt Client SAP (Mandant) 100 Applicable uniquement aux sources de données SAP. Identifiant client SAP à trois chiffres utilisé pour filtrer les lignes de données.
enabled Activation des modules true Indique si le module est activé.
external Fondation externe false Indique si la base est externe (ne crée pas d'ensemble de données cible).
tableSettings Paramètres de table src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml Chemin d'accès au fichier de configuration personnalisé Table settings, relatif à ce fichier de configuration.
Chemin d'accès recommandé : relatif au répertoire `config/` : '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
Chemin d'accès par défaut : '../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'

Données : modules : catalogues

Les catalogues Lakehouse externes permettent à Cortex Framework d'ingérer des tables externes à partir de catalogues et de partages BigLake Delta Sharing sans manifestes physiques.

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

Le tableau suivant décrit les paramètres de configuration du catalogue externe.

Paramètre Signification Valeur par défaut Description
id Identifiant du catalogue - Identifiant unique d'une instance de module de catalogue externe spécifique.
type Type de catalogue lakehouse_delta_share Type de catalogue. Valeur acceptée : lakehouse_delta_share.
bindsNamespaces Espaces de noms liés - Liste des préfixes d'espace de noms logiques liés par ce catalogue (par exemple, [sap_bdc]).
connectionSettings.catalogId ID du catalogue physique - ID du catalogue physique. Généralement identique à l'ID du module.
connectionSettings.projectId ID du projet - ID du projet Google Cloud dans lequel la connexion au catalogue est gérée.
connectionSettings.location Emplacement - Région géographique du catalogue.
connectionSettings.shares Partages - Liste des partages Delta Sharing à importer. Chaque partage doit contenir un shareId.
enabled Activation du catalogue true Indique si le catalogue est activé.

Données : Modules : Produits

Les modules de produits de données définissent les agrégations, les calculs et les jointures nécessaires pour transformer les données brutes en insights qui répondent à des cas d'utilisation métier spécifiques.

La configuration des produits de données permet de définir un ID unique, de définir des dépendances, ainsi que de référencer le module de base de données et l'ensemble de données cible dans lequel les résultats seront stockés.

La configuration détaillée des produits de données spécifiés est définie dans les fichiers référencés par la clé 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"

Le tableau suivant décrit les paramètres des modules de produits de données pour la configuration modules.products.

Paramètre Signification Valeur par défaut Description
moduleId Identifiant du module - Identifiant unique d'une instance de module de transformation spécifique.
modulePath Chemin d'accès au module - Définit le chemin d'accès avec espace de noms au module, à la logique métier ou au modèle appliqué. Format : {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}, par exemple cortex.sap.products.purchasing_organizational_structure, défini dans le dossier src/data_modules/{namespace_dir}/{system_type}/products/{product_name}.
dataTargetId Lien cible product_target Fait référence à l'ID de la liste des cibles vers laquelle transférer les données.
dependencyBindings Dépendance en amont sapModule: erp Spécifie les mappages pour satisfaire les dépendances des modules. Par exemple, en mappant sapModule sur erp.
enabled Activation des modules true Indique si le module est activé.
syncToKc Synchronisation de Knowledge Catalog true Indique si ce produit de données est synchronisé avec Knowledge Catalog.
tableSettings Paramètres de table src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml Chemin d'accès au fichier de configuration personnalisé Table settings, relatif à ce fichier de configuration.
Chemin d'accès recommandé : relatif au répertoire `config/` : '{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml'
Chemin d'accès par défaut : '../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml'

Environnement de déploiement

Cortex Framework utilise Dataform pour orchestrer les transformations SQL dans BigQuery. Le bloc deployment: définit la configuration Dataform, responsable de l'exécution des pipelines de données, y compris le projet de dépôt, l'emplacement, le nom du dépôt et le nom de l'espace de travail 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"

Le tableau suivant décrit les paramètres de localisation des cibles de déploiement (deployment.targets:).

Paramètre Signification Valeur par défaut Description
type Type de déploiement dataform Type des cibles de déploiement.
enabled Activé/ Désactivé true Indique si la cible de déploiement donnée est activée ou désactivée.
targetSettings.repositoryProjectId ID du projet de dépôt YOUR_REPO_PROJECT_ID ID du projet Google Cloud dans lequel le dépôt Dataform est géré.
targetSettings.repositoryRegion Région du dépôt us-central1 Région Google Cloud du dépôt Dataform (par exemple, us-central1 ou europe-west1).
targetSettings.repositoryName Nom du dépôt cortex-repository Nom spécifique du dépôt Dataform.
targetSettings.workspaceName Nom de l'espace de travail dev Espace de travail Dataform spécifique utilisé pour le cycle de déploiement.
targetSettings.serviceAccount Adresse e-mail du compte de service - Adresse e-mail du compte de service par défaut pour l'exécution du dépôt Dataform.

Fichier de configuration : table_settings.yaml

Ce guide explique comment utiliser le fichier table_settings.yaml pour configurer les tables de la base de données et des produits de données dans Google Cloud Cortex Framework.

Le fichier table_settings.yaml spécifique au module de données contrôle la façon dont les tables sources brutes sont conformées et dont les modèles de données analytiques sont matérialisés dans BigQuery. À l'aide de ce fichier, vous pouvez configurer des tags, des stratégies de matérialisation et des fonctionnalités avancées de performances BigQuery, comme le partitionnement ou le clustering.

Résolution dynamique des dépendances

Par défaut, Cortex Framework optimise l'empreinte de déploiement et le temps d'exécution en ne déployant et en ne compilant que les tables de base requises en tant que dépendances de vos produits de données activés. Si une table configurée dans table_settings.yaml ne comporte aucun produit de données en aval actif qui en dépend, elle est exclue du déploiement.

Pour remplacer cette optimisation et forcer le déploiement d'une table de fondation, vous pouvez définir l'attribut deployAlways sur true (voir Référence des paramètres de style de la fondation de données).

Dans Google Cloud Cortex Framework, un fichier de paramètres de tableau spécifique peut être attribué à chaque module (de base ou produit) dans le fichier de configuration du déploiement : config/config.yaml à l'aide de la propriété tableSettings.

Chemins de configuration

  • Paramètres personnalisés (recommandé) : pour personnaliser le comportement des tableaux, copiez le fichier par défaut dans votre répertoire de configuration, modifiez-le et référencez son chemin d'accès dans config/config.yaml. Voici les chemins d'accès recommandés (par rapport au répertoire config/) :
    • Modules de base : namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml (par exemple, config/cortex/sap/foundations/sap/table_settings.yaml)
    • Modules de produit : namespace_dir/system_type/products/product_name/custom_table_settings.yaml (par exemple, config/cortex/sap/products/accounting_documents/table_settings.yaml)
  • Solution de repli par défaut : si tableSettings est omis, le framework revient automatiquement à :
    • Modules de base : ../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
    • Modules de produits : ../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

Styles de configuration

Il existe deux styles de schéma distincts pour table_settings.yaml, selon la catégorie du module :

  1. Style de la couche de données : mappage basé sur une liste qui définit les relations entre le schéma source et le schéma cible, la gestion de la CDC (capture des données modifiées) et la mise en page BigQuery. Notez que la mise en page des paramètres de table de la base de données est spécifique au système source.

  2. Style du produit de données : mappage basé sur une carte (dictionnaire) qui définit la manière dont les vues ou les tables analytiques sont matérialisées (par exemple, en tant que vues, tables ou tables incrémentales) et optimisées.

Les deux styles sont compatibles avec trois sections de niveau racine pour séparer les configurations par version du système source (principalement utilisées pour SAP Data Foundation et les produits dépendants de SAP) :

  • ecc : paramètres appliqués uniquement lors du déploiement d'un système source SAP ECC.
  • s4 : paramètres appliqués uniquement lors du déploiement d'un système source SAP S/4HANA.
  • common : paramètres appliqués quelle que soit la version SAP (utilisés pour les paramètres conformes ou universels).

Style de base de données pour SAP ERP

Dans un module de base de données pour les systèmes sources SAP ERP, le fichier table_settings.yaml est structuré sous forme de liste d'éléments de tableau sous les clés ecc, s4 et common. Chaque élément mappe une table source brute à une table cible conforme et configure ses paramètres BigQuery.

Exemple de syntaxe YAML

common:
  - source:
      tableName: 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

Référence de paramètre

Paramètre Type Obligatoire Par défaut / Exemple Description
[].source object Oui [] Décrit la table dans le système source entrant de la base de données (par exemple, "sap_raw"). Consultez les paramètres de source.
[].target object Oui [] Décrit la table cible dans les ensembles de données de la base de données (par exemple, `sap_data_foundation`). Consultez les paramètres cibles.
ecc | s4 | common string Non [] Version ou dialecte du système source.
[].deployAlways boolean Non false Si la valeur est true, la table est toujours déployée et créée, même si les règles d'optimisation pourraient normalement l'ignorer. Consultez également Résolution dynamique des dépendances.
Paramètres de la source

Définit les caractéristiques de la table brute des données entrantes.

Paramètre Type Obligatoire Par défaut / Exemple Description
tableName string Oui bkpf Nom de la table source brute dans BigQuery (non sensible à la casse).
isCdc boolean Non true Indique si la table source contient des journaux de capture des données modifiées (CDC).

• true (par défaut) : le framework traite les journaux CDC (à l'aide des codes temporels et des indicateurs d'opération) pour reconstruire le dernier état conforme.

• false : la table est traitée comme un instantané complet.
Paramètres de ciblage

Définit la mise en page de la table conforme de sortie dans l'ensemble de données cible.

Paramètre Type Obligatoire Par défaut / Exemple Description
tableName string Non *(Même source)* Nom de la table conforme cible à créer. Si aucune valeur n'est spécifiée, le framework est défini par défaut sur la source tableName.
dataformTags array[string] Non [sap, finance] Liste des tags de métadonnées associés à l'action conforme dans Dataform. Il s'agit de chaînes arbitraires qui n'ont pas besoin d'être préenregistrées ni définies dans d'autres configurations. Elles peuvent être utilisées immédiatement pour filtrer les exécutions de pipeline (par exemple, à l'aide de dataform run --tags ...).
bigQueryLabels array[map] Non - Liste de paires clé/valeur représentant les libellés BigQuery à appliquer à la table cible (par exemple, clé : data_class, valeur : transactional).
clusterDetails map Non — Facultatif. Configuration du clustering BigQuery. Consultez Détails du clustering.
partitionDetails map Non — Facultatif. Configuration du partitionnement BigQuery. Pour en savoir plus, consultez Détails sur le partitionnement.

Style du produit de données

Dans un module de produit de données, le fichier table_settings.yaml (bloc ProductTableSettings) est structuré sous forme de dictionnaire (map) sous les clés racines ecc, s4 et common. Les clés de ce dictionnaire représentent les noms des tables ou vues analytiques cibles (non sensibles à la casse), et chaque valeur est un bloc de configuration Product TableItem (ProductTableItem) qui définit les stratégies de matérialisation, l'activation des tables et les optimisations des performances.

Exemple de syntaxe 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

Référence de paramètre

Paramètre Type Obligatoire Par défaut / Exemple Description
ecc | s4 | common map Non {} Carte des ressources analytiques cibles (tables ou vues) vers leurs descripteurs de configuration ProductTableItem.
[table_name] map Non {} Bloc de schéma du descripteur Product Table Item qui configure un élément analytique spécifique.
[table_name].enabled boolean Non true Détermine si la table ou la vue analytique ([table_name]) est active et incluse lors de la création de l'espace de travail Dataform.

• true (par défaut) : la définition de table est traitée, enrichie avec les propriétés table_config et copiée dans le répertoire de sortie Dataform.

• false : la définition de la table est ignorée lors de la compilation (SapProductBuilder consigne et omet la définition). La table ou la vue ne seront pas copiées ni intégrées à Dataform. Elles seront donc exclues du déploiement sans que les fichiers de définition source soient supprimés.
[table_name].materializationType string Non incremental Comment l'élément analytique est créé dans BigQuery.

Valeurs autorisées :

  • incremental (par défaut) : ne traite que les enregistrements nouveaux ou modifiés depuis la dernière exécution. Recommandé pour les grands ensembles de données transactionnelles afin de réduire les coûts.
  • table : recompile complètement la table à partir de zéro à chaque exécution.
  • view : déploie le composant en tant que vue SQL BigQuery (table virtuelle).
[table_name].dataformTags array[string] Non [sap, dataproduct] Tags de métadonnées associés au composant analytique dans Dataform. Il s'agit de chaînes arbitraires qui n'ont pas besoin d'être préenregistrées. Elles peuvent être utilisées immédiatement pour des exécutions de pipeline sélectives (par exemple, à l'aide de dataform run --tags ...).
[table_name].bigQueryLabels array[map] Non - Liste de paires clé/valeur représentant les libellés BigQuery à appliquer à l'actif analytique cible (par exemple, clé : data_class, valeur : master).
[table_name].clusterDetails map Non — Facultatif. Configuration du clustering BigQuery. Consultez Détails du clustering.
[table_name].partitionDetails map Non — Facultatif. Configuration du partitionnement BigQuery. Pour en savoir plus, consultez Détails sur le partitionnement.

Configurations BigQuery avancées

Les deux styles partagent la même structure pour optimiser le stockage et les performances des requêtes BigQuery grâce au clustering et au partitionnement.

Détails du clustering

Le clustering regroupe les données en fonction des valeurs de colonnes spécifiques. BigQuery trie les données de chaque bloc de stockage à l'aide de ces colonnes, ce qui accélère considérablement les requêtes qui filtrent (WHERE) ou joignent (JOIN) les données en fonction de ces colonnes.

clusterDetails:
  columns: [bukrs, gjahr]
Référence de paramètre
Paramètre Type Obligatoire Exemple Description
columns array[string] Oui [bukrs, gjahr] Liste ordonnée de quatre noms de colonnes maximum selon lesquels regrouper la table.

Contrainte : les colonnes doivent être alphanumériques et ne contenir que des traits de soulignement. L'ordre des colonnes dans la liste détermine la hiérarchie de tri.

Détails du partitionnement

Le partitionnement divise une grande table en segments physiques plus petits en fonction des valeurs d'une colonne de date, de code temporel ou d'entiers. Cela empêche BigQuery d'analyser l'intégralité de la table lorsqu'une requête ne demande qu'une plage spécifique de jours, de mois ou d'ID.

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
Référence de paramètre
Paramètre Type Obligatoire Exemple Description
column string Oui budat Nom de la colonne utilisée pour partitionner la table. Le nom ne doit comporter que des caractères alphanumériques et des traits de soulignement. Le type de colonne doit correspondre à partitionType.
partitionType string Oui time Stratégie de partitionnement.

Valeurs autorisées :

  • time : partitionne par unité de temps (colonne "Date", "Code temporel" ou "Date et heure").
  • DATE : partitionne explicitement par colonne de date.
  • integer : partitionne par plage d'entiers.
timeGrain string Non day Obligatoire si partitionType est time ou DATE. Définit la précision des partitions temporelles.

Valeurs autorisées : hour, day, month, year (non sensible à la casse).
rangeStart integer Non 1 Obligatoire si partitionType est défini sur integer. Valeur de début de la première partition (incluse).
rangeEnd integer Non 1000 Obligatoire si partitionType est défini sur integer. Valeur de fin de la dernière partition (exclusive).
rangeInterval integer Non 10 Obligatoire si partitionType est défini sur integer. Largeur de chaque intervalle de partition.

Exemples

Les exemples suivants présentent des modèles de configuration pour les modules de base de données et de produit de données. Ils expliquent comment personnaliser les tables cibles, optimiser la mise en page du stockage dans BigQuery et configurer les types de matérialisation.

1. Exemple de paramètres de tableau de données personnalisés

Cet exemple montre comment configurer une couche de base avec des tables transactionnelles partitionnées et mises en cluster (comme bseg et ekbe) à côté des tables de données standards :

# ==============================================================================
# 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. Exemple de paramètres de tableau de données produit personnalisés

Cet exemple montre comment configurer des types de matérialisation pour les produits de données analytiques en aval. Nous définissons les sales_documents transactionnelles comme incrémentielles pour optimiser les performances de compilation et réduire les coûts, tandis que les tables de données non transactionnelles telles que customers sont compilées en tant que tables standards :

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

Guides d'utilisation

Cette section fournit des guides détaillés pour les tâches de configuration courantes et les scénarios de déploiement personnalisés.

Personnaliser le champ d'application d'un tableau dans un module de base de données

Pour ajouter ou supprimer des tables dans un module de base de données existant sans créer de modules ni exécuter d'instances de pipeline distinctes :

  • Copiez les configurations table_settings.default.yaml par défaut dans le répertoire de configuration de votre espace de travail (par exemple, config/cortex/sap/foundations/sap/custom_table_settings.yaml).
  • Dans votre nouveau fichier, ajoutez vos tables personnalisées ou supprimez les tables standards inutilisées sous les clés ecc, s4 ou common, selon vos besoins :
common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]
  • Mettez à jour config/config.yaml pour faire référence au chemin d'accès aux paramètres de votre tableau personnalisé sous la propriété tableSettings du module :
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'
  • Pour enrichir le schéma de table de la table supplémentaire avec des annotations (descriptions de table et de colonne), créez un fichier d'annotation dans l'espace de noms du module Data Foundation que vous utilisez. Dans cet exemple, en fonction de modulePath: cortex.sap.foundations.sap, le chemin d'accès pour stocker votre fichier d'annotation custom_table_name.yaml est src/data_modules/cortex/sap/foundations/sap/annotations. Le format des fichiers d'annotation est décrit dans le guide d'extensibilité pour la base de données.

Configurer plusieurs instances d'un module d'infrastructure de données

Pour déployer deux instances de pipeline distinctes ou plus du même type de module (par exemple, pour prendre en charge plusieurs instances SAP, segmenter des tables, isoler des environnements ou cibler différents ensembles de données cibles).

Avant de commencer :

  • Assurez-vous que les tables sources existent dans votre ensemble de données brutes source.
  • Lorsque vous travaillez avec des modules de base de données SAP, vérifiez que la table de métadonnées DD03L contient des colonnes et des informations descriptives pour les tables personnalisées que vous souhaitez ingérer. Pour en savoir plus, consultez Exigences concernant SAP ERP.

Instructions :

  • Dans le fichier config/config.yaml, ajoutez des configurations cibles sous data.targets pour définir des ensembles de données cibles pour chaque instance de 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
  • Définissez plusieurs instances du module dans la liste data.modules.foundations. Attribuez à chaque instance un moduleId unique, ses propres ID d'ensemble de données cibles et, éventuellement, une configuration 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"
  • Créez le fichier config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml spécifiant le champ d'application personnalisé. Exemple :
common:
  - source:
      tableName: custom_sap_table_name
    target:
      dataformTags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day

  • Pour enrichir le schéma de table de la table supplémentaire avec des annotations (descriptions de table et de colonne), créez un fichier d'annotation dans l'espace de noms du module Data Foundation que vous utilisez. Dans cet exemple, en fonction de modulePath: cortex.sap.foundations.sap, le chemin d'accès pour stocker votre fichier d'annotation custom_table_name.yaml est src/data_modules/cortex/sap/foundations/sap/annotations. Le format des fichiers d'annotation est décrit dans le guide d'extensibilité pour la base de données.

  • Appliquez les modifications en exécutant le script de déploiement (uv run cortex-build-and-deploy), puis exécutez les actions Dataform comme décrit dans Étapes post-déploiement.