> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md). # Referência do YAML do workflow O formato YAML do workflow captura grafos de Nó, parâmetros e arestas do Transformation Builder para exportação, importação e compartilhamento entre ambientes Esta página documenta o formato YAML que o Transformation Builder usa para salvar e carregar\ configurações de fluxo de trabalho. O YAML é a representação interna do Builder de um design de fluxo de trabalho: ele captura o grafo de nós, parâmetros e arestas para que um fluxo de trabalho possa ser exportado,\ armazenado, compartilhado ou reimportado no Builder. Quando você agenda um fluxo de trabalho, o Builder compila o grafo de nós em uma única consulta SQL\ e o registra como uma função de banco de dados agendada. Essa consulta SQL e o job pg\_cron correspondente são\ o que é executado no seu banco de dados. O YAML não participa em tempo de execução. Se você quiser criar\ ou executar transformações independentemente do Builder, escreva e agende o SQL diretamente\ no seu banco de dados sem usar este formato. O formato tem 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 array edges separado para conexões. `edges` array para conexões. **Versão 1** é um formato mais antigo que usa uma `nodes` chave com inline `depends_on` referências para conexões. O Transformation Builder pode importar ambas as versões, mas sempre exporta a versão 2. {% columns %} {% column %} #### **Exportar** Produz um arquivo YAML no formato da versão 2. Você pode acionar uma exportação a partir do **Exportar** botão na barra de ferramentas do Transformation Builder, ou por meio da API. O arquivo exportado pode ser armazenado em um repositório, compartilhado com colegas ou reimportado\ no Transformation Builder em outro ambiente. {% endcolumn %} {% column %} #### **Importar** Aceita tanto a versão 2 (o formato atual) quanto a versão 1 (um formato anterior com `depends_on`conexões baseadas). Use o **Importar** função no Builder e selecione um `.yaml` ou `.yml` arquivo. {% endcolumn %} {% endcolumns %} ## Como a exportação é formada O gerador de exportação monta 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 em ordem de dependência e, por fim, o nó de saída. Se o grafo contiver um ciclo, é usada uma ordem de fallback (pela posição na lista de nós). 2. **Lista de origens por nó.** Para cada nó, o gerador coleta uma lista ordenada de IDs dos nós predecessores a partir das edges em que `target` é igual 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. Veja [estrutura cte\_nodes](#cte_nodes-structure) abaixo para detalhes dos campos. 4. **Montagem do YAML de nível superior.** O gerador combina o `cte_nodes` array com a lista de edges, metadados do fluxo de trabalho e campos opcionais (viewport, schedule) no documento final. ### Chaves de nível superior A raiz de um arquivo YAML da 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 exportações atuais. | | `nome` | Sempre | Nome do fluxo de trabalho. | | `descrição` | Sempre | Descrição do fluxo de trabalho. Pode ser uma string vazia. | | `cte_nodes` | Sempre | Array de registros de nós em ordem topológica. Veja [estrutura cte\_nodes](#cte_nodes-structure). | | `edges` | Sempre | Array de objetos de aresta. Veja [estrutura edges](#edges-structure). | | `output_node_id` | Quando existir um nó de saída | O ID do Nó de saída no fluxo de trabalho. | | `área de exibição` | Quando definido no fluxo de trabalho | Posição e nível de zoom do canvas: `{ x, y, zoom }`. Usado para restaurar o layout visual ao importar. | | `agendamento` | Quando o agendamento estiver ativado | Cronograma 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 fluxo de trabalho. | Campo | Descrição | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Identificador exclusivo do Nó (string). | | `tipo` | Tipo de Nó. Um dos: `telematics`, `business`, `filtro`, `reamostrar`, `sql`, `aritmético`, `personalizado`, `saída`. | | `label` | Nome de exibição mostrado no canvas. Se não for definido, usa o ID do Nó. | | `descrição` | Descrição do Nó. Pode ser uma string vazia. | | `posição` | Coordenadas do canvas como `{ x, y }`. | | `sources` | Lista ordenada de IDs dos 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ó. Veja a [Transformation Builder](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md) documentação para detalhes dos parâmetros por tipo de Nó. | | `width`, `height` | Opcional. Dimensões do canvas para o Nó, incluídas somente quando definidas explicitamente. | **Limpeza de parâmetros.** O `available_tables` e `available_columns` os campos são removidos de `params` durante a exportação. Esses campos são preenchidos em tempo de execução quando o Builder se conecta ao banco de dados e não devem ser armazenados em YAML. **Tipo SQL com várias fontes.** Quando um Nó do tipo `sql` tem duas ou mais fontes, a exportação adiciona um `join_spec` campo para o registro. Este é um array com um elemento contendo a configuração de junção: ```yaml join_spec: - type: "left" # join type (lowercase): left, inner, right, full on_condition: "a_node_telematics_1.device_id = a_node_business_1.device_id" ``` O `tipo` o valor é obtido do Nó `join_type` parâmetro (convertido para minúsculas), e `on_condition` é obtido de `join_condition`. Para nós SQL com duas fontes, as informações de junção aparecem em ambos `params` e `join_spec`. ### estrutura edges O `edges` array define conexões entre nós no grafo do fluxo de trabalho. ```yaml arestas: - fonte: "node-telematics-1" destino: "Nó-sql-1" - source: "nó-business-1" destino: "Nó-sql-1" ``` Cada aresta é um Objeto com dois campos: | Campo | Descrição | | -------- | --------------------------------------- | | `fonte` | O ID do Nó de onde a aresta se origina. | | `target` | O ID do Nó onde a aresta termina. | Os IDs de aresta da interface Builder não são preservados na exportação. Na importação, novos IDs de aresta 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 `versão: 2` ou a chave `cte_nodes`, o arquivo é processado como **versão 2**. * Caso contrário, **versão 1** é esperado. ### Importação da versão 2 O Builder percorre o `cte_nodes` array em ordem. Para cada registro: * O `id` e `tipo` são lidos. O tipo é convertido para minúsculas. Nós com tipo `python` são ignorados sem gerar um erro. * Os parâmetros são lidos da `params` chave (ou `config` como alternativa). Para `sql`-tipo de nós, se um `join_spec` campo estiver presente no registro, ele é atribuído à configuração de junção do nó. * O `edges` array é analisado em pares origem-destino, e novos IDs de arestas são gerados. * O `área de exibição` e `agendamento` os campos são preservados se estiverem presentes no YAML. ### Importação da versão 1 (compatibilidade com versões anteriores) Os arquivos da versão 1 usam uma `nodes` chave (array ou dicionário) e, opcionalmente, um `edges` array ou `depends_on` campos dentro de cada Nó. O Builder processa os arquivos da versão 1 da seguinte forma: * Os tipos de Nó compatíveis são os mesmos da versão 2: `telematics`, `business`, `filtro`, `reamostrar`, `sql`, `aritmético`, `personalizado`, `saída`. * As conexões entre nós podem ser definidas de duas maneiras: um array de nível superior, ou uma `edges` array `depends_on` lista dentro de cada Nó. * O `entradas` e `saídas` os 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 do Nó adequadamente para uma exibição correta na interface do Builder. ## modelo de estrutura YAML O modelo a seguir mostra a estrutura completa de um arquivo YAML da versão 2 com anotações: {% code expandable="true" %} ```yaml versão: 2 name: "workflow_name" description: "Descrição do fluxo de trabalho" cte_nodes: - id: "nó-id-1" type: telematics # telematics | business | filter | resample | # SQL | aritmética | personalizado | saída label: "Nome de exibição do Nó" description: "" position: { x: 100, y: 100 } sources: [] # empty for source nodes parâmetros: table_name: "tracking_data_core" time_column: "device_time" colunas: [device_id, device_time, speed] filter_condition: "" time_window_minutes: "" - id: "Nó-id-2" type: sql label: "Transformação SQL" description: "" position: { x: 400, y: 160 } sources: ["node-id-1", "node-id-3"] # IDs de predecessores ordenados parâmetros: 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 # altura: 400 arestas: - source: "nó-id-1" destino: "Nó-id-2" - fonte: "node-id-3" destino: "Nó-id-2" # campos de nível superior opcionais: output_node_id: "node-output-1" # Se existir um nó de saída viewport: { x: 0, y: 0, zoom: 1 } # posição do canvas na importação schedule: { cron: "0 0 * * *", timezone: "UTC" } # se o Agendamento estiver ativado ``` {% endcode %} ### Exemplo O exemplo a seguir mostra um fluxo de trabalho completo da versão 2 que lê dados de sensores de telemetria, une-os às descrições dos sensores do esquema de negócios, aplica uma transformação aritmética para converter o tipo de uma coluna e grava os resultados em uma tabela de saída. {% code expandable="true" %} ```yaml versão: 2 name: enriched_vehicle_metrics description: "Métricas enriquecidas do veículo a partir da telemática e descrição do sensor" cte_nodes: - id: nó-telematics-1 tipo: telemática label: "Dados brutos: telemática" description: "" position: { x: 100, y: 100 } sources: [] parâmetros: table_name: inputs time_column: device_time colunas: [device_id, device_time, value] filter_condition: "" time_window_minutes: "" - id: node-business-1 tipo: business label: "Dados brutos: Negócios" description: "" position: { x: 100, y: 220 } sources: [] parâmetros: table_name: sensor_description key_column: sensor_id colunas: [sensor_id, device_id, sensor_label] - id: nó-sql-1 type: sql label: "Transformação SQL" description: "" position: { x: 400, y: 160 } fontes: [node-telematics-1, node-business-1] parâmetros: 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: nó-arithmetic-1 tipo: aritmético label: "Aritmética" description: "" position: { x: 700, y: 160 } sources: [Nó-sql-1] parâmetros: expressões: - coluna: valor expressão: "value::numeric" expression_alias: value_num - id: Nó-output-1 tipo: saída label: "Saída" description: "" position: { x: 1000, y: 160 } fontes: [node-arithmetic-1] parâmetros: table_name: enriched_vehicle_metrics time_column: device_time primary_key: [device_id, device_time] write_mode: append arestas: - { source: node-telematics-1, target: node-sql-1 } - { source: nó-business-1, target: nó-sql-1 } - { source: node-sql-1, target: node-arithmetic-1 } - { source: nó-arithmetic-1, target: nó-output-1 } output_node_id: Nó-output-1 viewport: { x: 0, y: 0, zoom: 1 } schedule: { cron: "0 0 * * *", timezone: "UTC" } ``` {% endcode %} Este fluxo de trabalho executa as seguintes etapas: 1. **nó-telematics-1** leituras `device_id`, `device_time`, e `valor` colunas da `entradas` tabela na `raw_telematics_data` esquema. 2. **Nó-business-1** leituras `sensor_id`, `device_id`, e `sensor_label` do `sensor_description` tabela na `raw_business_data` esquema. 3. **Nó-sql-1** junta as duas fontes em `device_id` usando um `LEFT JOIN`, selecionando todas as colunas de telemetria mais a `sensor_label` da fonte de negócios. 4. **Nó-arithmetic-1** adiciona uma coluna calculada `value_num` ao converter o texto `valor` da coluna para um tipo numérico. 5. **Nó-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. {% hint style="info" %} A exportação não inclui `available_tables` ou `available_columns` em `params`. Esses campos são preenchidos dinamicamente quando o Builder se conecta ao banco de dados. Para nós SQL com duas fontes, as informações de junção aparecem em ambos os `params` e `join_spec`. {% endhint %} ## Próximas etapas * [**Transformation Builder**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md): Saiba como criar fluxos de trabalho usando a interface visual. * [**Modelos**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Configurações de fluxo de trabalho pré-criadas que você pode importar e adaptar no Transformation Builder. * [**Camada de transformação**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer.md): Entenda como os dados processados são organizados em esquemas e como consultá-los. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.