Configuração da implantação

Nesta página, explicamos as opções de configuração de implantação do Cortex Framework nas seguintes áreas:

Esta página também oferece guias de instruções com instruções detalhadas para casos de uso e cenários comuns de implantação.

Arquivo de configuração: config/config.yaml

O arquivo config/config.yaml, normalmente inicializado do modelo config/config.yaml.example, serve como a configuração principal da implantação do Cortex Framework. A configuração é dividida nestes blocos estruturais:

  1. Ambiente de build (buildEnvironment): controla a camada de orquestração de build, especificando o projeto Google Cloud central em que os cálculos de metadados intermediários, as validações de banco de dados e as pesquisas de esquema são faturados e executados.
  2. Dados (data): governa a arquitetura de dados lógicos. Esse bloco configura locais de conjuntos de dados, limites de namespace, detalhes de conexão para fontes de ingestão bruta, conjuntos de dados de destino e registra as instâncias do módulo de dados (foundations, catalogs e products).
  3. Implantação (deployment): configura implantações físicas do sistema de destino. Ele especifica os detalhes do repositório do Dataform (ID do projeto, local, nome do repositório e espaço de trabalho de desenvolvimento) em que os pipelines de transformação SQLX/JS compilados são implantados.

As seções a seguir fornecem um detalhamento de cada bloco.

Ambiente de build

O projeto de ambiente de build é aquele que recebe a cobrança por ações de build, como jobs do BigQuery que leem DD03L.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

A tabela a seguir descreve os parâmetros do ambiente de build.

Parâmetro Significado Valor padrão Descrição
buildEnvironment.buildProjectId ID do projeto de build YOUR_BUILD_PROJECT_ID Google Cloud : ID do projeto em que as operações de build são executadas.

Visão geral da seção "Dados"

A seção data: do arquivo de configuração define suas fontes e destinos de dados, além dos módulos específicos para a base e os produtos de dados. A estrutura geral é a seguinte:

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

Dados: local do BigQuery

Define o local dos conjuntos de dados de origem e destino do BigQuery.

Parâmetro Significado Valor padrão Descrição
data.bigQueryLocation Local do BigQuery US Local do conjunto de dados do BigQuery (por exemplo, US, us-central1 ou europe-west1).

Dados: namespace do Cortex

Define o namespace do Cortex Framework.

Parâmetro Significado Valor padrão Descrição
data.namespaces.name Nome do namespace - Nome do namespace do Cortex Framework. Por exemplo, cortex
data.namespaces.path Caminho do namespace - Caminho do namespace do Cortex Framework para subdiretórios usados nas pastas src e config. Por exemplo, cortex

Dados: fontes do BigQuery e conjuntos de dados de destino

A lista de conjuntos de dados define os pontos de conexão de dados brutos de entrada e os locais de armazenamento de saída para o framework. Cada conjunto de dados registra um identificador exclusivo mapeado para um projeto Google Cloud e um conjunto de dados do BigQuery específicos.

Os conjuntos de dados são referenciados nos módulos usando o ID exclusivo deles.

# 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

A tabela a seguir descreve os parâmetros de mapeamento de conjuntos de dados.

Parâmetro Significado Valor padrão Descrição
data.datasets.id ID do conjunto de dados - Define um identificador exclusivo para o conjunto de dados (por exemplo, sap_raw ou sap_foundation).
data.datasets.projectId ID do projeto - Faz referência ao Google Cloud ID do projeto que hospeda o conjunto de dados.
data.datasets.datasetId ID do conjunto de dados do BigQuery - Faz referência ao nome real do conjunto de dados do BigQuery.

Dados: módulos

Os módulos definem a estrutura e os componentes dos pipelines de dados do Dataform.

Dados: módulos: fundamentos

Esta seção configura os módulos da camada de base de dados que processam dados da camada bruta em uma representação padronizada dos registros mais recentes dos dados de origem. Caso a fonte forneça uma visualização dos registros mais recentes diretamente ou essas transformações sejam realizadas pelo conector do sistema de origem, o módulo poderá ser configurado como uma fonte externa de dados fundamentais.

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"

A tabela a seguir descreve os parâmetros dos módulos de base de dados para a configuração do modules.foundations.

Parâmetro Significado Valor padrão Descrição
moduleId Identificador do módulo erp Identificador exclusivo de uma instância específica do módulo de transformação da base de dados.
modulePath Caminho do módulo cortex.sap.foundations.sap Define o caminho com namespace para o módulo, a lógica de negócios ou o modelo aplicado. Formato: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap} (por exemplo, cortex.sap.foundations.sap).
dataSourceId Link da fonte sap_raw Referencia o "id" da lista data.datasets para extrair dados.
dataTargetId Link de destino sap_foundation Referencia o "id" da lista data.datasets para enviar dados.
moduleSettings.sapVersion Versão do sistema SAP ecc Aplicável apenas a fontes de dados SAP. Determina a lógica específica da origem para sistemas ecc (ECC) ou s4 (S/4HANA).
moduleSettings.mandt Cliente SAP (Mandant) 100 Aplicável apenas a fontes de dados SAP. O identificador de cliente SAP de três dígitos usado para filtrar linhas de dados.
enabled Ativação do módulo true Especifica se o módulo está ativado.
external Fundação externa false Especifica se a base é externa (não cria o conjunto de dados de destino).
tableSettings Configurações da tabela src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml Caminho para o arquivo de configuração personalizado Configurações da tabela, relativo a este arquivo de configuração.
Caminho recomendado: relativo ao diretório "config/": "{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml"
Caminho padrão: "../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml"

Dados: módulos: catálogos

Com os catálogos externos do lakehouse, o Cortex Framework pode ingerir tabelas externas de catálogos e compartilhamentos do BigLake Delta Sharing sem manifestos físicos.

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

A tabela a seguir descreve os parâmetros de configuração do catálogo externo.

Parâmetro Significado Valor padrão Descrição
id Identificador do catálogo - Identificador exclusivo de uma instância específica do módulo de catálogo externo.
type Tipo de catálogo lakehouse_delta_share O tipo de catálogo. É compatível com lakehouse_delta_share.
bindsNamespaces Namespaces vinculados - Uma lista de prefixos de namespace lógico vinculados por este catálogo (por exemplo, [sap_bdc]).
connectionSettings.catalogId ID do catálogo físico - ID do catálogo físico. Normalmente, é o mesmo que o ID do módulo.
connectionSettings.projectId ID do projeto - O ID do projeto Google Cloud em que a conexão do catálogo é gerenciada.
connectionSettings.location Local - A localização da região geográfica do catálogo.
connectionSettings.shares Compartilhamentos - Lista de compartilhamentos do Delta Sharing a serem importados. Cada compartilhamento precisa ter um shareId.
enabled Ativação do catálogo true Especifica se o catálogo está ativado.

Dados: módulos: produtos

Os módulos de produtos de dados definem as agregações, os cálculos e as junções necessárias para transformar dados brutos em insights que atendem a casos de uso comerciais específicos.

A configuração dos produtos de dados permite definir um ID exclusivo, definir dependências e referenciar o módulo de base de dados e o conjunto de dados de destino em que os resultados serão armazenados.

A configuração detalhada dos produtos de dados especificados é definida nos arquivos referenciados pela chave: 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"

A tabela a seguir descreve os parâmetros dos módulos de produtos de dados para configuração de modules.products.

Parâmetro Significado Valor padrão Descrição
moduleId Identificador do módulo - Identificador exclusivo de uma instância específica do módulo de transformação.
modulePath Caminho do módulo - Define o caminho com namespace para o módulo, a lógica de negócios ou o modelo aplicado. Formato: {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}, por exemplo, cortex.sap.products.purchasing_organizational_structure, definido na pasta src/data_modules/{namespace_dir}/{system_type}/products/{product_name}.
dataTargetId Link de destino product_target Referencia o "id" da lista de destinos para enviar dados.
dependencyBindings Dependência upstream sapModule: erp Especifica mapeamentos para atender às dependências do módulo. Por exemplo, mapear sapModule para erp.
enabled Ativação do módulo true Especifica se o módulo está ativado.
syncToKc Sincronização do Knowledge Catalog true Se o produto de dados está sincronizado com o Knowledge Catalog.
tableSettings Configurações da tabela src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml Caminho para o arquivo de configuração personalizado Configurações da tabela, relativo a este arquivo de configuração.
Caminho recomendado: relativo ao diretório "config/": "{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml"
Caminho padrão: "../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml"

Ambiente de implantação

O Cortex Framework usa o Dataform para orquestrar transformações de SQL no BigQuery. O bloco deployment: define a configuração do Dataform, responsável pela execução dos pipelines de dados, incluindo o projeto do repositório, o local, o nome do repositório e o nome do espaço de trabalho do 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"

A tabela a seguir descreve os parâmetros de local dos destinos de implantação (deployment.targets:).

Parâmetro Significado Valor padrão Descrição
type Tipo de implantação dataform Tipo dos destinos de implantação.
enabled Ativado/ Desativado true Especifica se o destino de implantação está ativado ou desativado.
targetSettings.repositoryProjectId ID do projeto do repositório YOUR_REPO_PROJECT_ID O ID do projeto Google Cloud em que o repositório do Dataform é gerenciado.
targetSettings.repositoryRegion Região do repositório us-central1 A região Google Cloud do repositório do Dataform (por exemplo, us-central1 ou europe-west1).
targetSettings.repositoryName Nome do repositório cortex-repository O nome específico do repositório do Dataform.
targetSettings.workspaceName Nome do espaço de trabalho dev O espaço de trabalho específico do Dataform usado para o ciclo de implantação.
targetSettings.serviceAccount E-mail da conta de serviço - E-mail da conta de serviço padrão para execução do repositório do Dataform.

Arquivo de configuração: table_settings.yaml

Este guia explica como usar o arquivo table_settings.yaml para configurar tabelas de base de dados e produtos de dados no Google Cloud Cortex Framework.

O arquivo table_settings.yaml específico do módulo de dados controla como as tabelas de origem bruta são conformadas e como os modelos de dados analíticos são materializados no BigQuery. Com esse arquivo, é possível configurar tags, estratégias de materialização e recursos avançados de desempenho do BigQuery, como particionamento ou clustering.

Resolução dinâmica de dependências

Por padrão, o Cortex Framework otimiza a pegada de implantação e o tempo de execução implantando e compilando apenas as tabelas de base necessárias como dependências dos produtos de dados ativados. Se uma tabela configurada em table_settings.yaml não tiver produtos de dados downstream ativos dependendo dela, ela será omitida da implantação.

Para substituir essa otimização e forçar a implantação de uma tabela de fundação, defina o atributo deployAlways como true. Consulte Referência de parâmetros de estilo da Data Foundation.

No Google Cloud Cortex Framework, cada módulo (base ou produto) pode receber um arquivo de configurações de tabela específico no arquivo de configuração de implantação: config/config.yaml usando a propriedade tableSettings.

Caminhos de configuração

  • Configurações personalizadas (recomendado): para personalizar os comportamentos da tabela, copie o arquivo padrão para o diretório de configuração, modifique-o e faça referência ao caminho dele em config/config.yaml. Os caminhos recomendados para uso (relativos ao diretório config/) são:
    • Módulos de fundação:namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml (por exemplo, config/cortex/sap/foundations/sap/table_settings.yaml)
    • Módulos de produtos:namespace_dir/system_type/products/product_name/custom_table_settings.yaml (por exemplo, config/cortex/sap/products/accounting_documents/table_settings.yaml)
  • Reversão padrão:se tableSettings for omitido, o framework vai fazer a reversão automática para:
    • Módulos de fundação:../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
    • Módulos de produtos:../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

Estilos de configuração

Há dois estilos de esquema distintos para table_settings.yaml, dependendo da categoria do módulo:

  1. Estilo da Data Foundation:mapeamento baseado em lista que define as relações de esquema de origem para destino, o processamento de CDC (captura de dados alterados) e o layout do BigQuery. O layout configurações da tabela de base de dados é específico do sistema de origem.

  2. Estilo do produto de dados:mapeamento baseado em mapa (dicionário) que define como as visualizações ou tabelas analíticas são materializadas (por exemplo, como visualizações, tabelas ou tabelas incrementais) e otimizadas.

Os dois estilos oferecem suporte a três seções de nível raiz para separar as configurações por versão do sistema de origem (usadas principalmente para a base de dados do SAP e produtos dependentes do SAP):

  • ecc: configurações aplicadas apenas ao implantar um sistema de origem do SAP ECC.
  • s4: configurações aplicadas apenas ao implantar um sistema de origem do SAP S/4HANA.
  • common: configurações aplicadas independente da versão do SAP (usadas para configurações universais ou em conformidade).

Estilo de base de dados para SAP ERP

Em um módulo de base de dados para sistemas de origem do SAP ERP, o arquivo table_settings.yaml é estruturado como uma lista de itens de tabela nas chaves ecc, s4 e common. Cada item mapeia uma tabela de origem bruta para uma tabela de destino em conformidade e configura as definições do BigQuery.

Exemplo de sintaxe 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

Referência de parâmetros

Parâmetro Tipo Obrigatório Padrão / Exemplo Descrição
[].source object Sim [] Descreve a tabela no sistema de origem de entrada da base de dados (por exemplo, "sap_raw"). Consulte as configurações de origem.
[].target object Sim [] Descreve a tabela de destino nos conjuntos de dados da base de dados (por exemplo, "sap_data_foundation"). Consulte as configurações de destino.
ecc | s4 | common string Não [] Versão ou dialeto do sistema de origem.
[].deployAlways boolean Não false Se for true, a tabela será sempre implantada e criada, mesmo que as regras de otimização a ignorem. Consulte também Resolução dinâmica de dependências.
Configurações de fonte

Define as características da tabela bruta de entrada.

Parâmetro Tipo Obrigatório Padrão / Exemplo Descrição
tableName string Sim bkpf O nome da tabela de origem bruta no BigQuery (sem diferenciação de maiúsculas e minúsculas).
isCdc boolean Não true Indica se a tabela de origem contém registros de captura de dados alterados (CDC).

• true (padrão): o framework processa registros de CDC (usando carimbos de data/hora de registros e flags de operação) para reconstruir o estado confirmado mais recente.

• false: a tabela é processada como um snapshot completo.
Configurações de segmentação

Define o layout da tabela de saída em conformidade no conjunto de dados de destino.

Parâmetro Tipo Obrigatório Padrão / Exemplo Descrição
tableName string Não *(Same as source)* O nome da tabela de destino em conformidade a ser criada. Se omitido, o framework vai usar o padrão da fonte tableName.
dataformTags array[string] Não [sap, finance] Uma lista de tags de metadados anexadas à ação em conformidade no Dataform. Essas são strings arbitrárias e não precisam ser pré-registradas ou definidas em outras configurações. Elas podem ser usadas imediatamente para filtrar execuções de pipeline (por exemplo, usando dataform run --tags ...).
bigQueryLabels array[map] Não - Uma lista de pares de chave-valor que representam rótulos do BigQuery a serem aplicados à tabela de destino (por exemplo, chave: data_class, valor: transactional).
clusterDetails map Não — Opcional. Configuração de clustering do BigQuery. Consulte Detalhes do cluster.
partitionDetails map Não — Opcional. Configuração de particionamento do BigQuery. Consulte Detalhes do particionamento.

Estilo do produto de dados

Em um módulo de produto de dados, o arquivo table_settings.yaml (bloco ProductTableSettings) é estruturado como um dicionário (mapa) nas chaves raiz ecc, s4 e common. As chaves desse dicionário representam os nomes da tabela ou visualização analítica de destino (sem diferenciação de maiúsculas e minúsculas), e cada valor é um bloco de configuração ProductTableItem (ProductTableItem) que define estratégias de materialização, ativação de tabela e otimizações de performance.

Exemplo de sintaxe 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

Referência de parâmetros

Parâmetro Tipo Obrigatório Padrão / Exemplo Descrição
ecc | s4 | common map Não {} Um mapa de recursos analíticos de destino (tabelas ou visualizações) para os descritores de configuração ProductTableItem.
[table_name] map Não {} O bloco de esquema do descritor Item da tabela de produtos que configura um recurso analítico específico.
[table_name].enabled boolean Não true Controla se a tabela ou visualização analítica ([table_name]) está ativa e incluída ao criar o espaço de trabalho do Dataform.

• true (padrão): a definição de tabela é processada, enriquecida com propriedades table_config e copiada para o diretório de saída do Dataform.

• false: a definição da tabela é ignorada durante o build (SapProductBuilder registra e omite). A tabela ou visualização não será copiada nem criada no Dataform, o que a exclui da implantação sem excluir os arquivos de definição de origem.
[table_name].materializationType string Não incremental Como o recurso analítico é criado no BigQuery.

Valores permitidos:

  • incremental (padrão): processa apenas registros novos ou atualizados desde a última execução. Recomendado para grandes conjuntos de dados transacionais para economizar custos.
  • table: recria completamente a tabela do zero a cada execução.
  • view: implanta o recurso como uma visualização SQL do BigQuery (tabela virtual).
[table_name].dataformTags array[string] Não [sap, dataproduct] Tags de metadados anexadas ao recurso analítico no Dataform. São strings arbitrárias que não precisam ser pré-registradas. Elas podem ser usadas imediatamente para execuções seletivas de pipelines (por exemplo, usando dataform run --tags ...).
[table_name].bigQueryLabels array[map] Não - Uma lista de pares de chave-valor que representam rótulos do BigQuery a serem aplicados ao recurso analítico de destino (por exemplo, chave: data_class, valor: master).
[table_name].clusterDetails map Não — Opcional. Configuração de clustering do BigQuery. Consulte Detalhes do cluster.
[table_name].partitionDetails map Não — Opcional. Configuração de particionamento do BigQuery. Consulte Detalhes do particionamento.

Configurações avançadas do BigQuery

Os dois estilos compartilham a mesma estrutura para otimizar o armazenamento e o desempenho da consulta do BigQuery usando clustering e particionamento.

Detalhes do clustering

O clustering coloca dados juntos com base nos valores em colunas específicas. O BigQuery classifica os dados em cada bloco de armazenamento usando essas colunas, o que acelera muito as consultas que filtram (WHERE) ou combinam (JOIN) nelas.

clusterDetails:
  columns: [bukrs, gjahr]
Referência de parâmetros
Parâmetro Tipo Obrigatório Exemplo Descrição
columns array[string] Sim [bukrs, gjahr] Uma lista ordenada de até quatro nomes de colunas para agrupar a tabela.

Restrição:as colunas precisam ser alfanuméricas e conter apenas sublinhados. A ordem das colunas na lista determina a hierarquia de classificação.

Detalhes do particionamento

O particionamento divide uma tabela grande em segmentos físicos menores com base nos valores de uma coluna de data, carimbo de data/hora ou número inteiro. Isso evita que o BigQuery verifique a tabela inteira quando uma consulta solicita apenas um intervalo específico de dias, meses ou IDs.

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
Referência de parâmetros
Parâmetro Tipo Obrigatório Exemplo Descrição
column string Sim budat O nome da coluna usada para particionar a tabela. Precisa ser alfanumérico e ter apenas sublinhados. O tipo de coluna precisa corresponder ao partitionType.
partitionType string Sim time A estratégia de particionamento.

Valores permitidos:

  • time: particiona por uma unidade de tempo (coluna de data, carimbo de data/hora ou data e hora).
  • DATE: particiona explicitamente por uma coluna de data.
  • integer: particiona por um intervalo de números inteiros.
timeGrain string Não day Obrigatório se partitionType for time ou DATE. Define a granularidade das partições de tempo.

Valores permitidos:hour, day, month, year (sem diferenciação entre maiúsculas e minúsculas).
rangeStart integer Não 1 Obrigatório se partitionType for integer. O valor inicial da primeira partição (inclusivo).
rangeEnd integer Não 1000 Obrigatório se partitionType for integer. O valor final da última partição (exclusivo).
rangeInterval integer Não 10 Obrigatório se partitionType for integer. A largura de cada intervalo de partição.

Exemplos

Os exemplos a seguir mostram modelos de configuração para módulos de base de dados e de produtos de dados, descrevendo como personalizar tabelas de destino, otimizar o layout de armazenamento no BigQuery e configurar tipos de materialização.

1. Exemplo de configurações personalizadas da tabela de dados básicos

Este exemplo mostra como configurar uma camada de base com tabelas transacionais agrupadas e particionadas (como bseg e ekbe) ao lado de tabelas de dados padrão:

# ==============================================================================
# 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. Exemplo de configurações personalizadas da tabela de produtos de dados

Este exemplo mostra como configurar tipos de materialização para produtos de dados analíticos downstream. Definimos sales_documents transacional como incremental para otimizar o desempenho da criação e economizar custos, enquanto as tabelas de dados não transacionais, como customers, são criadas como tabelas padrão:

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

Guias de instruções

Esta seção oferece guias detalhados para tarefas de configuração comuns e cenários de implantação personalizados.

Personalizar o escopo da tabela em um módulo de base de dados

Para adicionar ou remover tabelas em um módulo de base de dados sem criar novos módulos ou executar instâncias de pipeline separadas:

  • Copie as configurações padrão de table_settings.default.yaml para o diretório de configuração do espaço de trabalho (por exemplo, config/cortex/sap/foundations/sap/custom_table_settings.yaml).
  • No novo arquivo, adicione suas tabelas personalizadas ou remova as tabelas padrão não usadas nas chaves ecc, s4 ou common, conforme necessário:
common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]
  • Atualize config/config.yaml para referenciar o caminho das configurações de tabela personalizadas na propriedade tableSettings do módulo:
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'
  • Para enriquecer o esquema da tabela adicional com anotações (descrições de tabela e coluna), crie um arquivo de anotação no namespace do módulo de base de dados que você está usando. Neste exemplo, com base em modulePath: cortex.sap.foundations.sap, o caminho para armazenar o arquivo de anotação custom_table_name.yaml é src/data_modules/cortex/sap/foundations/sap/annotations. O formato dos arquivos de anotação é descrito no guia de extensibilidade para a base de dados.

Configurar várias instâncias de um módulo de base de dados

Para implantar duas ou mais instâncias de pipeline separadas do mesmo tipo de módulo (por exemplo, compatíveis com várias instâncias do SAP, para segmentar tabelas, isolar ambientes ou segmentar diferentes conjuntos de dados de destino).

Antes de começar:

  • Verifique se as tabelas de origem estão no conjunto de dados brutos de origem.
  • Ao trabalhar com módulos de base de dados do SAP, verifique se a tabela de metadados DD03L contém colunas e informações de descritor para as tabelas personalizadas que você pretende ingerir. Consulte os requisitos do SAP ERP para mais detalhes.

Instruções:

  • No arquivo config/config.yaml, adicione configurações de destino em data.targets para definir conjuntos de dados de destino para cada instância 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
  • Defina várias instâncias do módulo na lista data.modules.foundations. Dê a cada instância um moduleId exclusivo, IDs de conjunto de dados de destino próprios e, opcionalmente, uma configuração 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"
  • Crie o arquivo config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml especificando o escopo personalizado. Exemplo:
common:
  - source:
      tableName: custom_sap_table_name
    target:
      dataformTags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day

  • Para enriquecer o esquema da tabela adicional com anotações (descrições de tabela e coluna), crie um arquivo de anotação no namespace do módulo de base de dados que você está usando. Neste exemplo, com base em modulePath: cortex.sap.foundations.sap, o caminho para armazenar o arquivo de anotação custom_table_name.yaml é src/data_modules/cortex/sap/foundations/sap/annotations. O formato dos arquivos de anotação é descrito no guia de extensibilidade para a base de dados.

  • Aplique as mudanças executando o script de implantação (uv run cortex-build-and-deploy) e as ações do Dataform, conforme descrito em Etapas pós-implantação.