Referência YAML de workflow

Referência para o formato YAML de exportação/importação de workflow, incluindo campos de nós, arestas e diferenças de versão.

Esta página documenta o formato YAML que Transformation Builder usa para exportar e importar workflows. Use esta referência quando precisar compartilhar workflows entre ambientes, armazená-los em controle de versão ou integrar com sistemas de execução externos.

O formato possui duas versões. Versão 2 é o formato atual que o Transformation Builder produz na exportação. Ele organiza os nós como um array plano em ordem topológica (cte_nodes) com um edges array separado para conexões. Versão 1 é um formato mais antigo que usa uma chave nodes com depends_on referências embutidas para conexões. O Transformation Builder pode importar ambas as versões, mas sempre exporta a versão 2.

Exportar

Gera um arquivo YAML no formato versão 2. Você pode acionar uma exportação a partir do Exportar botão na barra de ferramentas do Transformation Builder, ou através da API. O arquivo exportado pode ser armazenado em um repositório, compartilhado com colegas ou passado para um runtime externo para execução.

Importar

Aceita tanto a versão 2 (o formato atual) quanto a versão 1 (um formato anterior com depends_on-based connections). Use a Importar função no Builder e selecione um .yaml ou .yml arquivo.

Como a exportação é formada

O gerador de exportação constrói o arquivo YAML em quatro etapas:

1. Ordenação topológica dos nós. O grafo de nós e arestas é ordenado de modo que os nós de origem venham primeiro, seguidos pelos nós de transformação na ordem de dependência, e finalmente o nó Output. Se o grafo contiver um ciclo, uma ordem alternativa (pela posição na lista de nós) é usada.

2. Lista de fontes por nó. Para cada nó, o gerador coleta uma lista ordenada de IDs de nós predecessores a partir das arestas onde target iguala-se ao ID do nó atual. Por exemplo, um nó SQL Transform com duas entradas terá uma sources lista contendo exatamente dois IDs na ordem correta.

3. array cte_nodes. Cada nó é gravado como um registro no cte_nodes array, em ordem topológica. Consulte estrutura cte_nodes abaixo para detalhes dos campos.

4. Montagem YAML no nível superior. O gerador combina o cte_nodes array com a lista de edges, metadados do workflow e campos opcionais (viewport, schedule) no documento final.

Chaves de nível superior

A raiz de um arquivo YAML versão 2 contém as seguintes chaves:

Chave	Presença	Descrição
version	Sempre	Número da versão do formato. Sempre 2 para as exportações atuais.
name	Sempre	Nome do workflow.
description	Sempre	Descrição do workflow. Pode ser uma string vazia.
cte_nodes	Sempre	Array de registros de nós em ordem topológica. Veja estrutura cte_nodes.
edges	Sempre	Array de objetos de aresta. Veja estrutura edges.
output_node_id	Quando um nó Output existe	O ID do nó Output no workflow.
viewport	Quando definido no workflow	Posição do Canvas e nível de zoom: { x, y, zoom }. Usado para restaurar o layout visual na importação.
schedule	Quando o agendamento está habilitado	Agenda de execução: { cron, timezone }. O cron padrão é 0 0 * * *, o fuso horário padrão é UTC.

estrutura cte_nodes

Cada entrada no cte_nodes array representa um nó no grafo do workflow.

Campo	Descrição
id	Identificador único do nó (string).
type	Tipo do nó. Um dos: telematics, business, filter, resample, sql, arithmetic, custom, output.
label	Nome exibido mostrado no canvas. Usa o ID do nó como substituto se não for definido.
description	Descrição do nó. Pode ser uma string vazia.
position	Coordenadas do Canvas como { x, y }.
sources	Lista ordenada de IDs de nós predecessores, derivada das arestas do grafo. Vazia para nós de origem.
params	Parâmetros de configuração do nó. Os campos específicos dependem do tipo de nó. Consulte a Transformation Builder documentação para detalhes de parâmetros por tipo de nó.
width, height	Opcional. Dimensões no Canvas para o nó, incluídas somente quando definidas explicitamente.

Limpeza de Params. O available_tables e available_columns campos são removidos de params durante a exportação. Esses campos são populados em tempo de execução quando o Builder se conecta ao banco de dados e não devem ser armazenados no YAML.

Tipo SQL com múltiplas fontes. Quando um nó do tipo sql possui duas ou mais fontes, a exportação adiciona um join_spec campo ao registro. Este é um array com um elemento contendo a configuração do join:

join_spec:
  - type: "left"       # tipo de join (lowercase): left, inner, right, full
    on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"

O type o valor é retirado do parâmetro join_type do nó (convertido para minúsculas), e on_condition é retirado de join_condition. Para nós SQL com duas fontes, a informação do join aparece em ambos params e join_spec.

estrutura edges

O edges array define conexões entre nós no grafo do workflow.

edges:
  - source: "node-telematics-1"
    target: "node-sql-1"
  - source: "node-business-1"
    target: "node-sql-1"

Cada aresta é um objeto com dois campos:

Campo	Descrição
source	O ID do nó onde a aresta se origina.
target	O ID do nó onde a aresta termina.

Os IDs das arestas na interface do Builder não são preservados na exportação. Na importação, novos IDs de arestas são gerados automaticamente.

Importar

Detecção de versão

O Builder determina a versão do formato YAML usando a seguinte lógica:

• Se a raiz contiver version: 2 ou a chave cte_nodes, o arquivo é processado como versão 2.

• Caso contrário, versão 1 é esperada.

Importação da versão 2

O Builder itera o cte_nodes array em ordem. Para cada registro:

• O id e type são lidos. O tipo é convertido para minúsculas. Nós com tipo python são ignorados sem gerar erro.

• Os parâmetros são lidos a partir da chave params (ou config como alternativa). Para nós do tipo sql-, se um campo join_spec estiver presente no registro, ele é atribuído à configuração de join do nó.

• O edges o array é analisado em pares fonte-destino, e novos IDs de arestas são gerados.

• O viewport e schedule campos são preservados se presentes no YAML.

Importação da versão 1 (compatibilidade retroativa)

Arquivos da versão 1 usam uma chave nodes (array ou dicionário) e opcionalmente um edges array ou depends_on campos dentro de cada nó.

O Builder processa arquivos da versão 1 da seguinte forma:

• Os tipos de nós suportados são os mesmos da versão 2: telematics, business, filter, resample, sql, arithmetic, custom, output.

• As conexões entre nós podem ser definidas de duas maneiras: um edges array de nível superior, ou uma depends_on lista dentro de cada nó.

• O inputs e outputs campos em cada nó são normalizados para objetos com { name, type } estrutura.

• Se as arestas incluírem sourceHandle ou targetHandle identificadores de porta, a importação ajusta as portas dos nós em conformidade para exibição correta na interface do Builder.

Template da estrutura YAML

O seguinte template mostra a estrutura completa de um arquivo YAML versão 2 com anotações:

version: 2
name: "workflow_name"
description: "Descrição do Workflow"

cte_nodes:
  - id: "node-id-1"
    type: telematics    # telematics | business | filter | resample |
                        # sql | arithmetic | custom | output
    label: "Nome de exibição do nó"
    description: ""
    position: { x: 100, y: 100 }
    sources: []         # vazio para nós de origem
    params:
      table_name: "tracking_data_core"
      time_column: "device_time"
      columns: [device_id, device_time, speed]
      filter_condition: ""
      time_window_minutes: ""

  - id: "node-id-2"
    type: sql
    label: "SQL Transform"
    description: ""
    position: { x: 400, y: 160 }
    sources: ["node-id-1", "node-id-3"]   # IDs de predecessores ordenados
    params:
      join_type: LEFT
      join_condition: "a_node_id_1.device_id = a_node_id_3.device_id"
      select_columns: ["a_node_id_1.*", "a_node_id_3.sensor_label"]
    join_spec:                             # adicionado para nós sql com 2+ fontes
      - type: "left"
        on_condition: "a_node_id_1.device_id = a_node_id_3.device_id"

    # campos opcionais por nó:
    # width: 250
    # height: 400

edges:
  - source: "node-id-1"
    target: "node-id-2"
  - source: "node-id-3"
    target: "node-id-2"

# campos opcionais de nível superior:
output_node_id: "node-output-1"           # se um nó Output existir
viewport: { x: 0, y: 0, zoom: 1 }        # posição do canvas na importação
schedule: { cron: "0 0 * * *", timezone: "UTC" }  # se o agendamento estiver habilitado

Exemplo

O exemplo a seguir mostra um workflow completo versão 2 que lê dados de sensores telemáticos, faz join com descrições de sensores do esquema business, aplica uma transformação aritmética para converter o tipo de uma coluna e grava os resultados em uma tabela de saída.

version: 2
name: enriched_vehicle_metrics
description: "Métricas de veículo enriquecidas a partir de telemática e descrição de sensores"

cte_nodes:
  - id: node-telematics-1
    type: telematics
    label: "Dados brutos: Telemática"
    description: ""
    position: { x: 100, y: 100 }
    sources: []
    params:
      table_name: inputs
      time_column: device_time
      columns: [device_id, device_time, value]
      filter_condition: ""
      time_window_minutes: ""

  - id: node-business-1
    type: business
    label: "Dados brutos: Business"
    description: ""
    position: { x: 100, y: 220 }
    sources: []
    params:
      table_name: sensor_description
      key_column: sensor_id
      columns: [sensor_id, device_id, sensor_label]

  - id: node-sql-1
    type: sql
    label: "SQL Transform"
    description: ""
    position: { x: 400, y: 160 }
    sources: [node-telematics-1, node-business-1]
    params:
      join_type: LEFT
      join_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"
      select_columns: ["a_node_telematics_1.*", "a_node_business_1.sensor_label"]
    join_spec:
      - type: "left"
        on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id"

  - id: node-arithmetic-1
    type: arithmetic
    label: "Arithmetic"
    description: ""
    position: { x: 700, y: 160 }
    sources: [node-sql-1]
    params:
      expressions:
        - column: value
          expression: "value::numeric"
          expression_alias: value_num

  - id: node-output-1
    type: output
    label: "Output"
    description: ""
    position: { x: 1000, y: 160 }
    sources: [node-arithmetic-1]
    params:
      table_name: enriched_vehicle_metrics
      time_column: device_time
      primary_key: [device_id, device_time]
      write_mode: append

edges:
  - { source: node-telematics-1, target: node-sql-1 }
  - { source: node-business-1, target: node-sql-1 }
  - { source: node-sql-1, target: node-arithmetic-1 }
  - { source: node-arithmetic-1, target: node-output-1 }

output_node_id: node-output-1
viewport: { x: 0, y: 0, zoom: 1 }
schedule: { cron: "0 0 * * *", timezone: "UTC" }

Este workflow realiza as seguintes etapas:

1. node-telematics-1 lê device_id, device_time, e value colunas da inputs tabela no raw_telematics_data schema.

2. node-business-1 lê sensor_id, device_id, e sensor_label do sensor_description tabela no raw_business_data schema.

3. node-sql-1 faz o join das duas fontes em device_id usando um LEFT JOIN, selecionando todas as colunas telemáticas mais o sensor_label do recurso business.

4. node-arithmetic-1 adiciona uma coluna calculada value_num convertendo o texto value coluna para um tipo numérico.

5. node-output-1 configura o resultado para ser gravado na enriched_vehicle_metrics tabela com append modo, usando device_id e device_time como chave primária.

A exportação não inclui available_tables ou available_columns em params. Esses campos são populados dinamicamente quando o Builder se conecta ao banco de dados. Para nós SQL com duas fontes, as informações de join aparecem em ambos params e join_spec.

Próximos passos

• Transformation Builder: Saiba como projetar workflows usando a interface visual.

• Camada Transformation: Entenda como os dados processados são organizados em schemas e como consultá-los.