Como configurar um namespace personalizado

Os namespaces personalizados servem como ambientes lógicos para empacotar e isolar sua base de dados e módulos 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 seu 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 de namespace personalizada

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 no config.yaml.
src/data_modules/custom_namespace_path/data_foundation/data_foundation_module_type Módulos de base de dados
Transformações de conjuntos de dados brutos para base. Cada base de dados é separada em um subdiretório e consiste em:
src/data_modules/custom_namespace_path/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, as dependências e a configuração do builder.
  • table_settings.default.yaml: configuração de Configurações da tabela
  • annotations/: descrições de coluna e campo.
  • definitions/: arquivos de origem SQLX ou JS do Dataform.
src/data_modules/custom_namespace_path/includes/ Helpers do JavaScript
Todos os arquivos JavaScript colocados aqui são automaticamente empacotados e disponibilizados para seus modelos do Dataform durante a compilação no caminho do namespace (por exemplo, includes/custom_namespace/).
src/data_modules/custom_namespace_path/common/ Ferramentas compartilhadas de namespace
Criadores, implantadores e outras ferramentas personalizadas com escopo de namespace.

Configuração de namespace personalizada

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

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

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/'

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_foundation_module
        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_module
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_foundation_module # References an existing foundation moduleId 
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_module_type/table_settings.yaml"

Código compartilhado de namespace personalizado

O namespace personalizado permite compartilhar artefatos de código entre os módulos. Os tipos de artefato compatíveis são:

  • includes: contém todos os helpers JavaScript que serão disponibilizados para seus artefatos do Dataform. Eles podem ser colocados na pasta: src/data_modules/custom_namespace_path/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_path/common/.

Entender e referenciar criadores

Os builders são classes geradoras do 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 de três níveis flexível:

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

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

Nível 1: criadores de substituição global

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 criadores de produtos de dados padrão da SAP no seu produto de dados personalizado, faça referência a sap_product no seu manifest.yaml:

# src/data_modules/custom_namespace_path/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: criadores com escopo de namespace

Se os módulos no seu 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_path/common/builders/my_builder.py.

  2. Decore a classe 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. Faça referência a ele no manifest.yaml do produto usando builder: my_builder.

Nível 3: criadores de produtos individuais

Para pipelines altamente exclusivos, é possível definir um builder com escopo exclusivo 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_path/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 automaticamente essa classe de forma dinâmica sem exigir registro ou decoradores.

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