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 Estrutura típica de subpastas
config/ Configuração de implantação do Cortex (obrigatório)
A criação de novos namespaces exige a configuração deles no config.yaml. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ Módulos de base de dados (opcional)
Transformações de conjuntos de dados brutos para base. 
-
src/data_modules/custom_namespace_path/data_product/ Definições de produtos de dados (opcional)
Contém lógica de negócios e modelos analíticos. Cada produto é separado em um subdiretório (por exemplo, your_product_name) e consiste em:
  • Readme: documentação do módulo
  • manifest.yaml: declara o tipo, as dependências e a configuração do builder.
  • annotations/: descrições de coluna e campo.
  • definitions/: arquivos de origem SQLX ou JS do Dataform.
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ Helpers do JavaScript (opcional)
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 do namespace (opcional)
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_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 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 físicas 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 personalizado, faça referência a sap_product em 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

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...
  1. 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_id/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...
  1. O compilador vai importar e executar automaticamente essa classe de forma dinâmica sem exigir registro ou decoradores.

Exemplo de namespace personalizado

No arquivo config/config.yaml, adicione este bloco abaixo de 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/'

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.