Configuración de implementación

En esta página, se explican las opciones de configuración de la implementación para Cortex Framework en las siguientes áreas:

En esta página, también se proporcionan guías prácticas con instrucciones paso a paso para casos de uso y situaciones de implementación comunes.

Archivo de configuración: config/config.yaml

El archivo config/config.yaml, que suele inicializarse a partir de la plantilla config/config.yaml.example, sirve como configuración principal para la implementación de Cortex Framework. La configuración se divide en los siguientes bloques estructurales:

  1. Entorno de compilación (buildEnvironment): Rige la capa de orquestación de compilación, especificando el proyecto Google Cloud central en el que se facturan y ejecutan los cálculos de metadatos intermedios, las validaciones de bases de datos y las búsquedas de esquemas.
  2. Datos (data): Rigen la arquitectura de datos lógicos. Este bloque configura las ubicaciones de los conjuntos de datos, los límites del espacio de nombres, los detalles de conexión para las fuentes de transferencia sin procesar y los conjuntos de datos de destino, y registra las instancias del módulo de datos (foundations, catalogs y products).
  3. Implementación (deployment): Configura las implementaciones del sistema de destino físico. Especifica los detalles del repositorio de Dataform (ID del proyecto, ubicación, nombre del repositorio y espacio de trabajo de desarrollo) en el que se implementan las canalizaciones de transformación compiladas de SQLX/JS.

En las siguientes secciones, se proporciona un desglose detallado de cada bloque.

Entorno de compilación

El proyecto de entorno de compilación es el proyecto al que se le facturan las acciones de compilación, como los trabajos de BigQuery que leen DD03L.

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

En la siguiente tabla, se describen los parámetros del entorno de compilación.

Parámetro Significado Valor predeterminado Descripción
buildEnvironment.buildProjectId ID de compilación del proyecto YOUR_BUILD_PROJECT_ID Google Cloud ID del proyecto en el que se ejecutan las operaciones de compilación.

Descripción general de la sección de datos

La sección data: del archivo de configuración define tus fuentes de datos, tus objetivos y los módulos específicos para la base de datos y los productos de datos. Su estructura general es la siguiente:

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

Datos: Ubicación de BigQuery

Define la ubicación de los conjuntos de datos de origen y destino de BigQuery.

Parámetro Significado Valor predeterminado Descripción
data.bigQueryLocation Ubicación de BigQuery US Ubicación del conjunto de datos de BigQuery (por ejemplo, US, us-central1 o europe-west1)

Datos: Espacio de nombres de Cortex

Define el espacio de nombres de Cortex Framework.

Parámetro Significado Valor predeterminado Descripción
data.namespaces.name Nombre del espacio de nombres - Es el nombre del espacio de nombres de Cortex Framework. Por ejemplo, cortex.
data.namespaces.path Ruta de acceso del espacio de nombres - Ruta del espacio de nombres del Cortex Framework para los subdirectorios que se usan en la carpeta src y config. Por ejemplo, cortex.

Datos: Conjuntos de datos de origen y destino de BigQuery

La lista de conjuntos de datos define los puntos de conexión de datos sin procesar entrantes y las ubicaciones de almacenamiento salientes para el framework. Cada conjunto de datos registra un identificador único asignado a un proyecto Google Cloud y un conjunto de datos de BigQuery específicos.

Se hace referencia a los conjuntos de datos desde los módulos con su ID único.

# 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

En la siguiente tabla, se describen los parámetros de asignación del conjunto de datos.

Parámetro Significado Valor predeterminado Descripción
data.datasets.id ID de conjunto de datos - Define un identificador único para el conjunto de datos (p.ej., sap_raw o sap_foundation).
data.datasets.projectId ID del proyecto - Hace referencia al ID del proyecto Google Cloud que aloja el conjunto de datos.
data.datasets.datasetId ID del conjunto de datos de BigQuery - Hace referencia al nombre real del conjunto de datos de BigQuery.

Datos: Módulos

Los módulos definen la estructura y los componentes de las canalizaciones de datos de Dataform.

Datos: Módulos: Conceptos básicos

En esta sección, se configuran los módulos de la capa de base de datos que procesan los datos de la capa sin procesar en una representación estandarizada de los registros más recientes de los datos de origen. En caso de que la fuente proporcione una vista de los registros más recientes directamente, o si el conector del sistema fuente realiza esas transformaciones, el módulo se puede configurar como una fuente externa de datos básicos.

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"

En la siguiente tabla, se describen los parámetros de los módulos de la base de datos para la configuración de modules.foundations.

Parámetro Significado Valor predeterminado Descripción
moduleId Identificador del módulo erp Es el identificador único de una instancia específica del módulo de transformación de la base de datos.
modulePath Ruta de acceso del módulo cortex.sap.foundations.sap Define la ruta con espacio de nombres al módulo, la lógica empresarial o la plantilla aplicada. Formato: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap} (por ejemplo, cortex.sap.foundations.sap).
dataSourceId Vínculo a la fuente sap_raw Hace referencia al "id" de la lista data.datasets para extraer datos.
dataTargetId Vínculo de destino sap_foundation Hace referencia al "id" de la lista data.datasets a la que se envían los datos.
moduleSettings.sapVersion Versión del sistema SAP ecc Solo se aplica a las fuentes de datos de SAP. Determina la lógica específica de la fuente para los sistemas ecc (ECC) o s4 (S/4HANA).
moduleSettings.mandt Cliente de SAP (Mandant) 100 Solo se aplica a las fuentes de datos de SAP. Es el identificador de cliente de SAP de 3 dígitos que se usa para filtrar las filas de datos.
enabled Habilitación del módulo true Especifica si el módulo está habilitado.
external Base externa false Especifica si la base es externa (no crea un conjunto de datos de destino).
tableSettings Configuración de tabla src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml Ruta de acceso al archivo de configuración personalizado de Table settings, relativa a este archivo de configuración.
Ruta recomendada: Relativa al directorio "config/": "{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml"
Ruta predeterminada: "../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml"

Datos: Módulos: Catálogos

Los catálogos externos de Lakehouse permiten que Cortex Framework transfiera tablas externas desde catálogos y recursos compartidos de BigLake Delta Sharing sin manifiestos 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

En la siguiente tabla, se describen los parámetros de configuración del catálogo externo.

Parámetro Significado Valor predeterminado Descripción
id Identificador de catálogo - Es el identificador único de una instancia específica del módulo de catálogo externo.
type Tipo de catálogo lakehouse_delta_share Es el tipo de catálogo. Admite lakehouse_delta_share.
bindsNamespaces Namespaces Bound - Es una lista de prefijos de espacios de nombres lógicos vinculados por este catálogo (p.ej., [sap_bdc]).
connectionSettings.catalogId ID de catálogo físico - Es el ID del catálogo físico. Por lo general, es el mismo que el ID del módulo.
connectionSettings.projectId ID del proyecto - ID del proyecto Google Cloud en el que se administra la conexión del catálogo.
connectionSettings.location Ubicación - Es la ubicación de la región geográfica del catálogo.
connectionSettings.shares Archivos compartidos - Lista de recursos compartidos de Delta Sharing que se importarán. Cada uso compartido debe contener un shareId.
enabled Habilitación del catálogo true Especifica si el catálogo está habilitado.

Datos: Módulos: Productos

Los módulos de productos de datos definen las agregaciones, los cálculos y las uniones necesarios para transformar los datos sin procesar en estadísticas que satisfagan casos de uso comerciales específicos.

La configuración de los productos de datos permite establecer un ID único, definir dependencias y hacer referencia al módulo de la base de datos y al conjunto de datos de destino en el que se almacenarán los resultados.

La configuración detallada de los productos de datos determinados se define en los archivos a los que hace referencia la clave: 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"

En la siguiente tabla, se describen los parámetros de los módulos de productos de datos para la configuración de modules.products.

Parámetro Significado Valor predeterminado Descripción
moduleId Identificador del módulo - Es el identificador único de una instancia de módulo de transformación específica.
modulePath Ruta de acceso del módulo - Define la ruta de acceso con espacio de nombres al módulo, la lógica empresarial o la plantilla aplicada. El formato es {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name}, por ejemplo, cortex.sap.products.purchasing_organizational_structure, definido en la carpeta src/data_modules/{namespace_dir}/{system_type}/products/{product_name}.
dataTargetId Vínculo de destino product_target Hace referencia al "id" de la lista de destinos para enviar datos.
dependencyBindings Dependencia upstream sapModule: erp Especifica las asignaciones para satisfacer las dependencias del módulo. Por ejemplo, mapear sapModule a erp.
enabled Habilitación del módulo true Especifica si el módulo está habilitado.
syncToKc Sincronización de Knowledge Catalog true Indica si este producto de datos está sincronizado con Knowledge Catalog.
tableSettings Configuración de tabla src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml Ruta de acceso al archivo de configuración personalizado de Table settings, relativa a este archivo de configuración.
Ruta recomendada: Relativa al directorio "config/": "{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml"
Ruta predeterminada: "../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml"

Entorno de implementación

Cortex Framework usa Dataform para coordinar las transformaciones de SQL en BigQuery. El bloque deployment: define la configuración de Dataform, que es responsable de la ejecución de las canalizaciones de datos, incluido el proyecto del repositorio, la ubicación, el nombre del repositorio y el nombre del espacio de trabajo de 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"

En la siguiente tabla, se describen los parámetros de ubicación de los destinos de implementación (deployment.targets:).

Parámetro Significado Valor predeterminado Descripción
type Tipo de implementación dataform Es el tipo de destinos de implementación.
enabled Habilitado/ Inhabilitado true Especifica si el destino de la implementación determinado está habilitado o inhabilitado.
targetSettings.repositoryProjectId ID del proyecto del repositorio YOUR_REPO_PROJECT_ID ID del proyecto Google Cloud en el que se administra el repositorio de Dataform.
targetSettings.repositoryRegion Región del repositorio us-central1 Es la región Google Cloud del repositorio de Dataform (por ejemplo, us-central1 o europe-west1).
targetSettings.repositoryName Nombre del repositorio cortex-repository Nombre específico del repositorio de Dataform.
targetSettings.workspaceName Nombre del espacio de trabajo dev Es el espacio de trabajo específico de Dataform que se usa para el ciclo de implementación.
targetSettings.serviceAccount Correo electrónico de la cuenta de servicio - Es la dirección de correo electrónico de la cuenta de servicio predeterminada para la ejecución del repositorio de Dataform.

Archivo de configuración: table_settings.yaml

En esta guía, se explica cómo usar el archivo table_settings.yaml para configurar las tablas de la base de datos y los productos de datos en Google Cloud Cortex Framework.

El archivo table_settings.yaml específico del módulo de datos controla cómo se ajustan las tablas de origen sin procesar y cómo se materializan los modelos de datos analíticos en BigQuery. Con este archivo, puedes configurar etiquetas, estrategias de materialización y funciones avanzadas de rendimiento de BigQuery, como la partición o el agrupamiento en clústeres.

Resolución de dependencias dinámica

De forma predeterminada, Cortex Framework optimiza la huella de implementación y el tiempo de ejecución implementando y compilando solo las tablas de base que se requieren como dependencias de los productos de datos habilitados. Si una tabla configurada en table_settings.yaml no tiene ningún producto de datos activo que dependa de ella, se omite de la implementación.

Para anular esta optimización y forzar la implementación de una tabla de base, puedes establecer el atributo deployAlways en true (consulta la referencia del parámetro de estilo de la base de datos).

En Google Cloud Cortex Framework, a cada módulo (de base o de producto) se le puede asignar un archivo de configuración de tabla específico en el archivo de configuración de implementación: config/config.yaml con la propiedad tableSettings.

Rutas de configuración

  • Configuración personalizada (recomendada): Para personalizar el comportamiento de la tabla, copia el archivo predeterminado en tu directorio de configuración, modifícalo y haz referencia a su ruta de acceso en config/config.yaml. Las rutas de acceso recomendadas para usar (relativas al directorio config/) son las siguientes:
    • Módulos de base: namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml (p.ej., config/cortex/sap/foundations/sap/table_settings.yaml)
    • Módulos de productos: namespace_dir/system_type/products/product_name/custom_table_settings.yaml (p.ej., config/cortex/sap/products/accounting_documents/table_settings.yaml)
  • Respaldo predeterminado: Si se omite tableSettings, el framework recurre automáticamente a lo siguiente:
    • Módulos de base: ../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
    • Módulos de productos: ../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

Estilos de configuración

Hay dos estilos de esquema distintos para table_settings.yaml según la categoría del módulo:

  1. Estilo de la base de datos: Es un mapeo basado en listas que define las relaciones del esquema de origen a destino, el control de CDC (captura de datos modificados) y el diseño de BigQuery. Ten en cuenta que el diseño de la configuración de la tabla de la base de datos es específico del sistema fuente.

  2. Estilo del producto de datos: Es una asignación basada en mapas (diccionario) que define cómo se materializan y optimizan las vistas o tablas analíticas (p.ej., como vistas, tablas o tablas incrementales).

Ambos estilos admiten tres secciones de nivel raíz para separar las configuraciones por versión del sistema fuente (se usan principalmente para SAP Data Foundation y productos dependientes de SAP):

  • ecc: Parámetros de configuración que se aplican solo cuando se implementa un sistema fuente de SAP ECC.
  • s4: Parámetros de configuración que se aplican solo cuando se implementa un sistema de origen de SAP S/4HANA.
  • common: Se aplica la configuración independientemente de la versión de SAP (se usa para la configuración universal o conforme).

Estilo de base de datos para SAP ERP

En un módulo de base de datos para los sistemas de origen de SAP ERP, el archivo table_settings.yaml se estructura como una lista de elementos de tabla en las claves ecc, s4 y common. Cada elemento asigna una tabla de origen sin procesar a una tabla de destino conforme y configura sus parámetros de BigQuery.

Ejemplo de sintaxis de 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

Referencia del parámetro

Parámetro Tipo Obligatorio Predeterminado / ejemplo Descripción
[].source object Sí [] Describe la tabla en el sistema de origen entrante de la base de datos (p.ej., "sap_raw"). Consulta la configuración de la fuente.
[].target object Sí [] Describe la tabla de destino en los conjuntos de datos de la base de datos (p.ej., "sap_data_foundation"). Consulta la configuración de destino.
ecc | s4 | common string No [] Versión o dialecto del sistema de origen
[].deployAlways boolean No false Si es true, la tabla siempre se implementa y compila, incluso si las reglas de optimización podrían omitirla. Consulta también Resolución de dependencias dinámicas
Configuración de las fuentes

Define las características de la tabla de entrada sin procesar.

Parámetro Tipo Obligatorio Predeterminado / ejemplo Descripción
tableName string Yes - Nombre de la tabla de origen sin procesar en BigQuery (no distingue mayúsculas de minúsculas) tal como la importa el conector del sistema de origen .
sapTableName string No - Nombre de la tabla de SAP (sin distinción entre mayúsculas y minúsculas) tal como se define en las tablas de metadatos del sistema de origen (p.ej., "DD03L"). Si se define, este parámetro se usa como nombre para la tabla de la base de datos correspondiente.
isCdc boolean No true Indica si la tabla de origen contiene registros de captura de datos modificados (CDC).

• true (predeterminado): El framework procesa los registros de CDC (con marcas de tiempo de registros y marcas de operación) para reconstruir el estado confirmado más reciente.

• false: La tabla se procesa como una instantánea completa.
Configuración del objetivo

Define el diseño de la tabla de salida conforme en el conjunto de datos de destino.

Parámetro Tipo Obligatorio Predeterminado / ejemplo Descripción
tableName string No *(Igual que la fuente)* Es el nombre de la tabla de destino que se creará. Si se omite, el framework usa de forma predeterminada la fuente tableName.
dataformTags array[string] No [sap, finance] Es una lista de etiquetas de metadatos adjuntas a la acción conforme en Dataform. Son cadenas arbitrarias y no es necesario registrarlas previamente ni definirlas en otras configuraciones. Se pueden usar de inmediato para filtrar las ejecuciones de la canalización (p. ej., con dataform run --tags ...).
bigQueryLabels array[map] No - Es una lista de pares clave-valor que representan las etiquetas de BigQuery que se aplicarán a la tabla de destino (por ejemplo, clave: data_class, valor: transactional).
clusterDetails map No — Es opcional. Es la configuración del agrupamiento en clústeres de BigQuery. Consulta Detalles del agrupamiento en clústeres.
partitionDetails map No — Es opcional. Es la configuración de la partición de BigQuery. Consulta los detalles de la partición.

Estilo del producto de datos

En un módulo de producto de datos, el archivo table_settings.yaml (bloque ProductTableSettings) se estructura como un diccionario (mapa) en las claves raíz ecc, s4 y common. Las claves de este diccionario representan los nombres de la vista o la tabla analítica de destino (sin distinción entre mayúsculas y minúsculas), y cada valor es un bloque de configuración de Product TableItem (ProductTableItem) que define estrategias de materialización, habilitación de tablas y optimizaciones del rendimiento.

Ejemplo de sintaxis de 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

Referencia del parámetro

Parámetro Tipo Obligatorio Predeterminado / ejemplo Descripción
ecc | s4 | common map No {} Es un mapa de los recursos analíticos de destino (tablas o vistas) a sus descriptores de configuración de ProductTableItem.
[table_name] map No {} Es el bloque de esquema del descriptor Product Table Item que configura un activo analítico específico.
[table_name].enabled boolean No true Controla si la tabla o vista analítica ([table_name]) está activa y se incluye cuando se compila el espacio de trabajo de Dataform.

• true (predeterminado): Se procesa la definición de la tabla, se enriquece con propiedades de table_config y se copia en el directorio de salida de Dataform.

• false: Se omite la definición de la tabla durante la compilación (SapProductBuilder la registra y la omite). La tabla o la vista no se copiarán ni se compilarán en Dataform, lo que las excluirá de la implementación sin borrar los archivos de definición de origen.
[table_name].materializationType string No incremental Cómo se compila el activo analítico en BigQuery

Valores permitidos:

  • incremental (predeterminado): Solo procesa los registros nuevos o actualizados desde la última ejecución. Se recomienda para grandes conjuntos de datos transaccionales para ahorrar costos.
  • table: Vuelve a crear la tabla desde cero en cada ejecución.
  • view: Implementa el activo como una vista de SQL de BigQuery (tabla virtual).
[table_name].dataformTags array[string] No [sap, dataproduct] Son las etiquetas de metadatos adjuntas al recurso analítico en Dataform. Son cadenas arbitrarias y no es necesario registrarlas previamente. Se pueden usar de inmediato para ejecuciones de canalizaciones selectivas (por ejemplo, con dataform run --tags ...).
[table_name].bigQueryLabels array[map] No - Es una lista de pares clave-valor que representan las etiquetas de BigQuery que se aplicarán al activo analítico objetivo (por ejemplo, clave: data_class, valor: master).
[table_name].clusterDetails map No — Es opcional. Es la configuración del agrupamiento en clústeres de BigQuery. Consulta Detalles del agrupamiento en clústeres.
[table_name].partitionDetails map No — Es opcional. Es la configuración de la partición de BigQuery. Consulta los detalles de la partición.

Configuraciones avanzadas de BigQuery

Ambos estilos comparten la misma estructura para optimizar el almacenamiento y el rendimiento de las consultas de BigQuery a través del agrupamiento en clústeres y la partición.

Detalles del agrupamiento en clústeres

La agrupación en clústeres coloca los datos en la misma ubicación según los valores de columnas específicas. BigQuery ordena los datos dentro de cada bloque de almacenamiento con estas columnas, lo que acelera drásticamente las consultas que filtran (WHERE) o unen (JOIN) en ellas.

clusterDetails:
  columns: [bukrs, gjahr]
Referencia del parámetro
Parámetro Tipo Obligatorio Ejemplo Descripción
columns array[string] Yes [bukrs, gjahr] Es una lista ordenada de hasta cuatro nombres de columnas por las que se agrupará la tabla en clústeres.

Restricción: Las columnas deben ser alfanuméricas y contener solo guiones bajos. El orden de las columnas en la lista determina la jerarquía de clasificación.

Detalles de la partición

La partición divide una tabla grande en segmentos físicos más pequeños según los valores de una columna de fecha, marca de tiempo o número entero. Esto evita que BigQuery analice la tabla completa cuando una consulta solo solicita un rango específico de días, meses o IDs.

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
Referencia del parámetro
Parámetro Tipo Obligatorio Ejemplo Descripción
column string Yes budat Nombre de la columna que se usa para particionar la tabla. Solo debe contener caracteres alfanuméricos y guiones bajos. El tipo de columna debe coincidir con el partitionType.
partitionType string Yes time Es la estrategia de partición.

Valores permitidos:

  • time: Particiona por una unidad de tiempo (columna de fecha, marca de tiempo o fecha y hora).
  • DATE: Particiona de forma explícita por una columna de fecha.
  • integer: Particiona por un rango de números enteros.
timeGrain string No day Obligatorio si partitionType es time o DATE. Define la granularidad de las particiones de tiempo.

Valores permitidos: hour, day, month, year (no distingue mayúsculas de minúsculas).
rangeStart integer No 1 Obligatorio si partitionType es integer. Es el valor inicial de la primera partición (inclusivo).
rangeEnd integer No 1000 Obligatorio si partitionType es integer. Es el valor final de la última partición (exclusivo).
rangeInterval integer No 10 Obligatorio si partitionType es integer. Es el ancho de cada intervalo de partición.

Ejemplos

En los siguientes ejemplos, se muestran plantillas de configuración para los módulos de la base de datos y del producto de datos, en las que se describe cómo personalizar las tablas de destino, optimizar el diseño de almacenamiento en BigQuery y configurar los tipos de materialización.

1. Ejemplo de configuración de la tabla de datos personalizada

En este ejemplo, se muestra cómo configurar una capa de base con tablas transaccionales particionadas y agrupadas (como bseg y ekbe) junto con tablas de datos estándares:

# ==============================================================================
# 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. Ejemplo de configuración personalizada de la tabla de productos de datos

En este ejemplo, se muestra cómo configurar los tipos de materialización para los productos de datos analíticos posteriores. Establecemos sales_documents transaccional como incremental para optimizar el rendimiento de la compilación y ahorrar costos, mientras que las tablas de datos no transaccionales, como customers, se compilan como tablas estándar:

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

Guías prácticas

En esta sección, se proporcionan guías paso a paso para tareas de configuración comunes y situaciones de implementación personalizadas.

Personaliza el alcance de la tabla en un módulo de la base de datos

Para agregar o quitar tablas dentro de un módulo de base de datos existente sin crear módulos nuevos ni ejecutar instancias de canalización separadas, sigue estos pasos:

  • Copia la configuración predeterminada de table_settings.default.yaml en el directorio de configuración de tu espacio de trabajo (por ejemplo, config/cortex/sap/foundations/sap/custom_table_settings.yaml).
  • En tu archivo nuevo, agrega tus tablas personalizadas o quita las tablas estándar que no se usen en las claves ecc, s4 o common según sea necesario:
common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]
  • Actualiza config/config.yaml para que haga referencia a la ruta de acceso de la configuración de tu tabla personalizada en la propiedad tableSettings del 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 el esquema de la tabla adicional con anotaciones (descripciones de tablas y columnas), crea un archivo de anotaciones en el espacio de nombres del módulo de la base de datos que estás usando. En este ejemplo, según modulePath: cortex.sap.foundations.sap, la ruta para almacenar tu archivo de anotación custom_table_name.yaml es src/data_modules/cortex/sap/foundations/sap/annotations. El formato de los archivos de anotación se describe en la guía de extensibilidad para la base de datos.

Configura varias instancias de un módulo de base de datos

Implementar dos o más instancias de canalización separadas del mismo tipo de módulo (por ejemplo, para admitir varias instancias de SAP, segmentar tablas, aislar entornos o segmentar diferentes conjuntos de datos de destino)

Antes de comenzar:

  • Asegúrate de que las tablas de origen existan en tu conjunto de datos sin procesar de origen.
  • Cuando trabajes con módulos de la base de datos de SAP, verifica que la tabla de metadatos DD03L contenga columnas y la información del descriptor para las tablas personalizadas que deseas transferir. Consulta los requisitos de SAP ERP para obtener más detalles.

Instrucciones:

  • En el archivo config/config.yaml, agrega configuraciones de destino en data.targets para definir conjuntos de datos de destino para cada instancia de canalización:
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
  • Define varias instancias del módulo en la lista data.modules.foundations. Asigna a cada instancia un moduleId único, sus propios IDs de conjunto de datos objetivo y, de manera opcional, la configuración de 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 el archivo config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml que especifica el alcance personalizado. P. ej.:
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 el esquema de la tabla adicional con anotaciones (descripciones de tablas y columnas), crea un archivo de anotaciones en el espacio de nombres del módulo de la base de datos que estás usando. En este ejemplo, según modulePath: cortex.sap.foundations.sap, la ruta para almacenar tu archivo de anotación custom_table_name.yaml es src/data_modules/cortex/sap/foundations/sap/annotations. El formato de los archivos de anotación se describe en la guía de extensibilidad para la base de datos.

  • Aplica los cambios ejecutando la secuencia de comandos de implementación (uv run cortex-build-and-deploy) y, luego, ejecuta las acciones de Dataform como se describe en Pasos posteriores a la implementación.