Referencia YAML de flujo de trabajo

Referencia del formato YAML de exportación/importación de flujos de trabajo, incluidos campos de nodos, aristas y diferencias entre versiones.

Esta página documenta el formato YAML que Transformation Builder utiliza para exportar e importar flujos de trabajo. Use esta referencia cuando necesite compartir flujos de trabajo entre entornos, almacenarlos en control de versiones o integrarlos con sistemas de ejecución externos.

El formato tiene dos versiones. Versión 2 es el formato actual que Transformation Builder genera al exportar. Organiza los nodos como una matriz plana en orden topológico (cte_nodes) con una edges matriz separada para las conexiones. Versión 1 es un formato anterior que utiliza una nodes clave con depends_on referencias en línea para las conexiones. Transformation Builder puede importar ambas versiones, pero siempre exporta la versión 2.

Exportar

Genera un archivo YAML en el formato de la versión 2. Puede iniciar una exportación desde el Exportar botón en la barra de herramientas de Transformation Builder, o a través de la API. El archivo exportado puede almacenarse en un repositorio, compartirse con colegas o pasarse a un tiempo de ejecución externo para su ejecución.

Importar

Acepta tanto la versión 2 (el formato actual) como la versión 1 (un formato anterior con depends_onconexiones basadas en ). Use la Importar función en el Builder y seleccione un .yaml o .yml archivo.

Cómo se forma la exportación

El generador de exportación construye el archivo YAML a través de cuatro pasos:

1. Orden topológico de los nodos. El grafo de nodos y aristas se ordena de modo que los nodos fuente vengan primero, seguidos por los nodos de transformación en orden de dependencia, y finalmente el nodo Output. Si el grafo contiene un ciclo, se usa un orden alternativo (por posición en la lista de nodos).

2. Lista de fuentes por nodo. Para cada nodo, el generador recopila una lista ordenada de IDs de nodos predecesores a partir de las aristas donde target iguala el ID del nodo actual. Por ejemplo, un nodo SQL Transform con dos entradas tendrá una sources lista que contiene exactamente dos IDs en el orden correcto.

3. matriz cte_nodes. Cada nodo se escribe como un registro en la cte_nodes matriz, en orden topológico. Vea estructura cte_nodes a continuación para los detalles de los campos.

4. Ensamblado YAML de nivel superior. El generador combina la cte_nodes matriz con la lista de edges, los metadatos del flujo de trabajo y campos opcionales (viewport, schedule) en el documento final.

Claves de nivel superior

La raíz de un archivo YAML de la versión 2 contiene las siguientes claves:

Clave	Presencia	Descripción
version	Siempre	Número de versión del formato. Siempre 2 para las exportaciones actuales.
name	Siempre	Nombre del flujo de trabajo.
description	Siempre	Descripción del flujo de trabajo. Puede ser una cadena vacía.
cte_nodes	Siempre	Matriz de registros de nodos en orden topológico. Vea estructura cte_nodes.
edges	Siempre	Matriz de objetos edge. Vea estructura edges.
output_node_id	Cuando existe un nodo Output	El ID del nodo Output en el flujo de trabajo.
viewport	Cuando está establecido en el flujo de trabajo	Posición del lienzo y nivel de zoom: { x, y, zoom }. Usado para restaurar la disposición visual al importar.
schedule	Cuando el schedule está habilitado	Horario de ejecución: { cron, timezone }. El cron predeterminado es 0 0 * * *, la zona horaria predeterminada es UTC.

estructura cte_nodes

Cada entrada en la cte_nodes matriz representa un nodo en el grafo del flujo de trabajo.

Campo	Descripción
id	Identificador único del nodo (cadena).
type	Tipo de nodo. Uno de: telematics, business, filter, resample, sql, arithmetic, custom, output.
label	Nombre para mostrar que se muestra en el lienzo. Si no está establecido, se usa el ID del nodo.
description	Descripción del nodo. Puede ser una cadena vacía.
position	Coordenadas del lienzo como { x, y }.
sources	Lista ordenada de IDs de nodos predecesores, derivada de las aristas del grafo. Vacía para nodos fuente.
params	Parámetros de configuración del nodo. Los campos específicos dependen del tipo de nodo. Vea la Transformation Builder documentación para detalles de parámetros por tipo de nodo.
width, height	Opcional. Dimensiones en el lienzo del nodo, incluidas solo cuando se establecen explícitamente.

Limpieza de Params. El available_tables y available_columns campos se eliminan de params durante la exportación. Estos campos se completan en tiempo de ejecución cuando el Builder se conecta a la base de datos y no deben almacenarse en YAML.

Tipo SQL con múltiples fuentes. Cuando un nodo de tipo sql tiene dos o más fuentes, la exportación añade un join_spec campo al registro. Esto es una matriz con un elemento que contiene la configuración del join:

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

El type el valor se toma del parámetro join_type (convertido a minúsculas), y on_condition se toma de join_condition. Para nodos SQL con dos fuentes, la información de join aparece en ambas params y join_spec.

estructura edges

El edges la matriz define las conexiones entre nodos en el grafo del flujo de trabajo.

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

Cada edge es un objeto con dos campos:

Campo	Descripción
source	El ID del nodo donde se origina la arista.
target	El ID del nodo donde termina la arista.

Los IDs de las aristas desde la interfaz del Builder no se conservan en la exportación. En la importación, se generan automáticamente nuevos IDs para las aristas.

Importar

Detección de versión

El Builder determina la versión del formato YAML usando la siguiente lógica:

• Si la raíz contiene version: 2 o la clave cte_nodes, el archivo se procesa como versión 2.

• De lo contrario, versión 1 se espera.

Importación versión 2

El Builder itera la cte_nodes matriz en orden. Para cada registro:

• El id y type se leen. El tipo se convierte a minúsculas. Los nodos con tipo python se omiten sin generar un error.

• Los parámetros se leen desde la params clave (o config como respaldo). Para nodos de tipo sql-type, si un campo join_spec está presente en el registro, se asigna a la configuración de join del nodo.

• El edges la matriz se analiza en pares fuente-destino, y se generan nuevos IDs para las aristas.

• El viewport y schedule los campos se preservan si están presentes en el YAML.

Importación versión 1 (compatibilidad hacia atrás)

Los archivos de la versión 1 usan una nodes clave (matriz o diccionario) y opcionalmente un edges matriz o depends_on campos dentro de cada nodo.

El Builder procesa los archivos de la versión 1 de la siguiente manera:

• Los tipos de nodo compatibles son los mismos que en la versión 2: telematics, business, filter, resample, sql, arithmetic, custom, output.

• Las conexiones entre nodos pueden definirse de dos maneras: un edges matriz de nivel superior, o una depends_on lista dentro de cada nodo.

• El inputs y outputs los campos en cada nodo se normalizan a objetos con { name, type } estructura.

• Si las aristas incluyen identificadores de puerto sourceHandle o targetHandle , la importación ajusta los puertos de los nodos en consecuencia para su correcta visualización en la interfaz del Builder.

Plantilla de estructura YAML

La siguiente plantilla muestra la estructura completa de un archivo YAML de la versión 2 con anotaciones:

version: 2
name: "workflow_name"
description: "Descripción del flujo de trabajo"

cte_nodes:
  - id: "node-id-1"
    type: telematics    # telematics | business | filter | resample |
                        # sql | arithmetic | custom | output
    label: "Nombre para mostrar del nodo"
    description: ""
    position: { x: 100, y: 100 }
    sources: []         # vacío para nodos fuente
    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: "Transformación SQL"
    description: ""
    position: { x: 400, y: 160 }
    sources: ["node-id-1", "node-id-3"]   # IDs de predecesores 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:                             # añadido para nodos sql con 2+ fuentes
      - type: "left"
        on_condition: "a_node_id_1.device_id = a_node_id_3.device_id"

    # campos opcionales por nodo:
    # width: 250
    # height: 400

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

# campos opcionales de nivel superior:
output_node_id: "node-output-1"           # si existe un nodo Output
viewport: { x: 0, y: 0, zoom: 1 }        # posición del lienzo al importar
schedule: { cron: "0 0 * * *", timezone: "UTC" }  # si la programación está habilitada

Ejemplo

El siguiente ejemplo muestra un flujo de trabajo completo de la versión 2 que lee datos de sensores telemáticos, los une con descripciones de sensores del esquema business, aplica una transformación aritmética para convertir el tipo de una columna y escribe los resultados en una tabla de salida.

version: 2
name: enriched_vehicle_metrics
description: "Métricas de vehículo enriquecidas a partir de telemática y descripción de sensores"

cte_nodes:
  - id: node-telematics-1
    type: telematics
    label: "Datos crudos: Telematics"
    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: "Datos crudos: 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: "Transformación SQL"
    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: "Aritmética"
    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 flujo de trabajo realiza los siguientes pasos:

1. node-telematics-1 lee device_id, device_timey value columnas desde la inputs tabla en el raw_telematics_data esquema.

2. node-business-1 lee sensor_id, device_idy sensor_label desde el sensor_description tabla en el raw_business_data esquema.

3. node-sql-1 une las dos fuentes en device_id usando un LEFT JOIN, seleccionando todas las columnas telemáticas más el sensor_label desde la fuente business.

4. node-arithmetic-1 agrega una columna calculada value_num al convertir el texto value de la columna a un tipo numérico.

5. node-output-1 configura que el resultado se escriba en la enriched_vehicle_metrics tabla con append modo, usando device_id y device_time como clave primaria.

La exportación no incluye available_tables o available_columns en params. Estos campos se completan dinámicamente cuando el Builder se conecta a la base de datos. Para nodos SQL con dos fuentes, la información de join aparece en ambas params y join_spec.

Próximos pasos

• Transformation Builder: Aprenda cómo diseñar flujos de trabajo usando la interfaz visual.

• Capa de transformación: Entienda cómo se organiza los datos procesados en esquemas y cómo consultarlos.