Como configurar um namespace personalizado

Os namespaces personalizados servem como ambientes lógicos para empacotar e isolar os módulos de base de dados e de produtos de dados analíticos. A execução em um namespace personalizado dedicado permite gerenciar as opções de configuração e implantação de forma independente, oferecendo isolamento para o ambiente. Um dos principais benefícios dessa separação é que você pode extrair atualizações e melhorias futuras do namespace cortex no Google Cloud Cortex Framework sem o risco de substituir ou corromper seus módulos personalizados. Recomendamos criar seus módulos personalizados em um namespace dedicado.

Estrutura de pastas do namespace personalizado

As pastas de namespace do Cortex Framework são usadas para empacotar e isolar artefatos de módulos personalizados. A estrutura de pastas de um namespace personalizado é definida na tabela:

Caminho do diretório Finalidade e descrição
config/ Configuração de implantação do Cortex (obrigatório)
A criação de novos namespaces exige a configuração deles em config.yaml.
src/data_modules/custom_namespace/data_foundation/data_foundation_module_type Módulos de base de dados
Transformações de conjuntos de dados brutos em base de dados. Cada base de dados é separada em um subdiretório e consiste em:
src/data_modules/custom_namespace/data_product/data_product_module_type Definições de produtos de dados
Contém lógica de negócios e modelos analíticos. Cada produto é separado em um subdiretório e consiste em:
  • Readme: documentação do módulo
  • manifest.yaml: declara o tipo de builder, as dependências e a configuração.
  • table_settings.default.yaml: Configuração das definições de tabela
  • annotations/: descrições de colunas e campos.
  • definitions/: arquivos de origem SQLX ou JS do Dataform.
src/data_modules/custom_namespace/includes/ Auxiliares do JavaScript
Todos os arquivos JavaScript colocados aqui são empacotados automaticamente e disponibilizados para os modelos do Dataform durante a compilação no caminho do namespace (por exemplo, includes/custom_namespace/).
src/data_modules/custom_namespace/common/ Ferramentas compartilhadas do namespace
Builders personalizados, implantadores e outras ferramentas com escopo no namespace.

Configuração do namespace personalizado

Um novo namespace: custom_namespace pode ser definido estendendo a seção correspondente do arquivo config.yaml, criando um novo diretório em src/data_modules/ e adicionando os novos recursos de código do módulo.

Para que o compilador do Google Cloud Cortex Framework reconheça seu namespace e módulos personalizados, registre-os no arquivo de configuração global (por exemplo, config/config.yaml).

Etapa A: registrar o namespace

No bloco data.namespaces, adicione os metadados do namespace:

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

Etapa B: configurar módulos personalizados

Registre seus módulos personalizados em data.modules.foundation ou data.modules.product. Use o formato separado por pontos custom_namespace.module_type para o campo type:

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_data_foundation_module_type
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/table_settings.default.yaml"
        # Custom table settings file, relative to 'config/' directory
        tableSettings: "custom_namespace/data_foundation/data_foundation_module_type/table_settings.yaml"
        
    product:
      - moduleId: custom_namespace_data_product_module_type
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_data_foundation_module_type # References an existing foundation moduleId 
        dataTargetId: product_target
        # Custom table settings file, relative to 'config/' directory
        # tableSettings: "custom_namespace/data_product/data_product_module_type/table_settings.yaml"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_product/data_product_module_type/table_settings.default.yaml"

Código compartilhado do namespace personalizado

O namespace personalizado oferece suporte ao compartilhamento de artefatos de código entre os módulos. Os tipos de artefato com suporte são:

  • includes : contém todos os auxiliares do JavaScript que serão disponibilizados para os artefatos do Dataform. Eles podem ser colocados na pasta: src/data_modules/custom_namespace/includes/.
  • builders : todas as classes de gerador personalizadas que podem compilar o código-fonte do módulo em artefatos do Dataform. Eles podem ser colocados em src/data_modules/custom_namespace/common/.

Como entender e referenciar builders

Os builders são classes de gerador Python que compilam os arquivos de origem do módulo em saídas do Dataform. O Google Cloud Cortex Framework compila módulos usando uma sequência de resolução de builder flexível de três níveis:

Sequência de resolução de criadores de extensibilidade do Google Cloud Cortex Framework

Figura 1. Sequência de resolução de builders de extensibilidade do Cortex Framework.

Nível 1: builders de fallback globais

O framework inclui builders altamente robustos localizados em src/common/builders/. Esses builders são registrados globalmente e podem ser usados por qualquer namespace personalizado.

Por exemplo, para usar os builders de produtos de dados SAP padrão para seu produto de dados personalizado, referencie sap_product no manifest.yaml:

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

Nível 2: builders com escopo no namespace

Se os módulos dentro do namespace personalizado exigirem um compilador especializado, registre um builder personalizado para esse namespace.

  1. Crie um arquivo de builder em src/data_modules/custom_namespace/common/builders/my_builder.py.

  2. Decore a classe do builder com @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...

  3. Referencie-o no manifest.yaml do produto usando builder: my_builder.

Nível 3: builders individuais de produtos

Para pipelines altamente exclusivos, defina um builder com escopo exclusivamente para um único produto de dados.

  1. Basta criar um arquivo chamado builder.py diretamente na pasta do produto de dados (por exemplo, src/data_modules/custom_namespace/data_product/data_product_module_type/builder.py).

  2. Defina uma subclasse de BaseBuilder ou ProductBuilder dentro dela:

     from common.builders.base import ProductBuilder

 class UniqueSalesPerformanceBuilder(ProductBuilder):
     # Implement unique build logic here...

  3. O compilador vai importar e executar essa classe automaticamente de forma dinâmica, sem exigir registro ou decoradores.

Nas próximas etapas: criação de módulos de base de dados e criação de módulos de produtos de dados, você vai aprender a adicionar módulos de dados ao namespace.