Configura un espacio de nombres personalizado

Los espacios de nombres personalizados sirven como entornos lógicos para empaquetar y aislar tu base de datos y los módulos de productos de datos analíticos. Ejecutar dentro de un espacio de nombres personalizado dedicado te permite administrar las opciones de configuración y de implementación de forma independiente, lo que proporciona aislamiento para tu entorno. Un beneficio clave de esta separación es que puedes extraer sin problemas futuras actualizaciones y mejoras del espacio de nombres cortex en Google Cloud Cortex Framework sin el riesgo de anular o dañar tus módulos personalizados. Te recomendamos que crees tus módulos personalizados dentro de un espacio de nombres dedicado.

Estructura de carpetas del espacio de nombres personalizado

Las carpetas de espacio de nombres de Cortex Framework se usan para empaquetar y aislar artefactos de módulos personalizados. La estructura de carpetas de un espacio de nombres personalizado se define en la tabla:

Ruta de acceso del directorio Propósito y descripción Estructura de subcarpetas típica
config/ Configuración de implementación de Cortex (obligatorio)
Para crear espacios de nombres nuevos, es necesario configurarlos en config.yaml. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ Módulos de base de datos (opcional)
Transformaciones de conjuntos de datos de datos sin procesar a base de datos. 
-
src/data_modules/custom_namespace_path/data_product/ Definiciones de productos de datos (opcional)
Contiene lógica empresarial y modelos analíticos. Cada producto se separa en un subdirectorio (por ejemplo, your_product_name) y consta de lo siguiente:
  • Readme: Documentación del módulo
  • manifest.yaml: Declara el tipo de compilador, las dependencias y la configuración.
  • annotations/: Descripciones a nivel de columna y campo
  • definitions/: Archivos de origen SQLX o JS de Dataform
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ Auxiliares de JavaScript (opcional)
Cualquier archivo de JavaScript que se coloque aquí se empaqueta automáticamente y se pone a disposición de tus modelos de Dataform durante la compilación en la ruta de acceso del espacio de nombres (por ejemplo, includes/custom_namespace/). 
-
src/data_modules/custom_namespace_path/common/ Herramientas compartidas del espacio de nombres (opcional)
Compiladores, implementadores y otras herramientas personalizados con alcance de espacio de nombres 
-

Configuración del espacio de nombres personalizado

Se puede definir un espacio de nombres nuevo: custom_namespace. Para ello, extiende la sección correspondiente del archivo config.yaml, crea un directorio nuevo en src/data_modules/ y agrega los nuevos recursos de código del módulo.

Para que el compilador de Google Cloud Cortex Framework reconozca tu espacio de nombres y módulos personalizados, debes registrarlos en tu archivo de configuración global (p.ej., config/config.yaml).

Paso A: Registra el espacio de nombres

En el bloque data.namespaces, agrega los metadatos de tu espacio de nombres:

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name:  custom_namespace    # <-- Name of custom namespace
      path:  custom_namespace_path/  # <-- Folder name that is used for custom namespace, points to subdirectory of 'src/data_modules/'

Paso B: Configura módulos personalizados

Registra tus módulos personalizados en data.modules.foundation o data.modules.product. Usa el formato separado por puntos custom_namespace.module_type para el campo type:

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_foundation_module_id
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        tableSettings: "config/custom_namespace_path/data_foundation/sap/table_settings.yaml"

    product:
      - moduleId: custom_namespace_data_product_id
        type: custom_namespace.data_product_id  # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: erp_ecc            # References an existing foundation moduleId
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_id/table_settings.yaml"

Código compartido del espacio de nombres personalizado

El espacio de nombres personalizado admite el uso compartido de artefactos de código entre sus módulos. Los tipos de artefactos admitidos son los siguientes:

  • includes : Contiene cualquier auxiliar de JavaScript que estará disponible para tus artefactos de Dataform. Se pueden colocar en la carpeta src/data_modules/custom_namespace_path/includes/.
  • builders : Cualquier clase de generador personalizado que pueda compilar el código fuente de tu módulo en artefactos de Dataform. Se pueden colocar en src/data_modules/custom_namespace_path/common/.

Comprende y haz referencia a los compiladores

Los compiladores son clases de generadores de Python que compilan tus archivos de origen de módulos en resultados físicos de Dataform. Google Cloud Cortex Framework compila módulos con una secuencia de resolución de compiladores de tres niveles flexible:

Secuencia de resolución de compiladores de extensibilidad de Google Cloud Cortex Framework

Figura 1. Secuencia de resolución de compiladores de extensibilidad de Cortex Framework

Nivel 1: Compiladores de resguardo globales

El framework incluye compiladores muy sólidos ubicados en src/common/builders/. Estos compiladores se registran de forma global y pueden ser usados por cualquier espacio de nombres personalizado.

Por ejemplo, para usar los compiladores de productos de datos estándar de SAP para tu producto personalizado, haz referencia a sap_product en tu manifest.yaml:

# src/data_modules/custom_namespace_path/data_product/data_product_id/manifest.yaml
type: data_product_id
builder: sap_product     # Automatically resolves to the global SapProductBuilder fallback
dependencies:
  sapModule:
    type: sap
    supportedVersions:
      - ecc
      - s4

Nivel 2: Compiladores con alcance de espacio de nombres

Si los módulos dentro de tu espacio de nombres personalizado requieren un compilador especializado, puedes registrar un compilador personalizado para ese espacio de nombres.

  1. Crea un archivo de compilador en src/data_modules/custom_namespace_path/common/builders/my_builder.py.

  2. Decora tu clase de compilador con @builder_registry.register("my_builder") :

   from common.builders.base import ProductBuilder
   from common.registry import builder_registry

   @builder_registry.register("my_builder")
   class MyCustomProductBuilder(ProductBuilder):
       # Implement build logic here...
  1. Haz referencia a ella en el manifest.yaml de tu producto con builder: my_builder.

Nivel 3: Compiladores individuales a nivel de producto

Para las canalizaciones altamente únicas, puedes definir un compilador con alcance exclusivo para un solo producto de datos.

  1. Simplemente crea un archivo llamado builder.py directamente dentro de la carpeta de tu producto de datos (p.ej., src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py).

  2. Define una subclase de BaseBuilder o ProductBuilder dentro de ella:

   from common.builders.base import ProductBuilder

   class UniqueSalesPerformanceBuilder(ProductBuilder):
       # Implement unique build logic here...
  1. El compilador importará y ejecutará automáticamente esta clase de forma dinámica sin requerir ningún registro ni decorador.

Ejemplo de espacio de nombres personalizado

En el archivo config/config.yaml, agrega este bloque en data.namespaces:

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name: sap_bookingdatamodel # <-- Name of custom namespace: sap_bookingdatamodel
      path: sap_bookingdatamodel/  # <-- Folder name that is used for custom namespace:sap_bookingdatamodel, points to subdirectory of 'src/data_modules/'

En los siguientes pasos: Creación de módulos de base de datos y Creación de módulos de productos de datos, aprenderás a agregar módulos de datos al espacio de nombres.