Referencia YAML del flujo de trabajo

El formato YAML del flujo de trabajo captura grafos de nodos de Transformation Builder, parámetros y aristas para exportación, importación y uso compartido entre entornos

Esta página documenta el formato YAML que Transformation Builder usa para guardar y cargar configuraciones de flujo de trabajo. El YAML es la representación interna del Builder de un diseño de flujo de trabajo: captura el grafo de nodos, los parámetros y las conexiones para que un flujo de trabajo pueda exportarse, almacenarse, compartirse o reimportarse en el Builder.

Cuando programa un flujo de trabajo, el Builder compila el grafo de nodos en una sola consulta SQL y la registra como una función de base de datos programada. Esa consulta SQL y su tarea de pg_cron son las que se ejecutan en su base de datos. El YAML no interviene en tiempo de ejecución. Si desea crear o ejecutar transformaciones de forma independiente de Builder, escriba y programe el SQL directamente en su base de datos sin usar este formato.

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

Exportar

Genera un archivo YAML en formato de versión 2. Puede iniciar una exportación desde el Exportar botón de 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 reimportarse en Transformation Builder en otro entorno.

Importar

Acepta tanto la versión 2 (el formato actual) como la versión 1 (un formato anterior con depends_onconexiones basadas en nodos). 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 mediante cuatro pasos:

1. Ordenamiento topológico de nodos. El grafo de nodos y conexiones se ordena de modo que los nodos fuente aparezcan primero, seguidos por los nodos de transformación en orden de dependencias y, por último, el nodo de salida. Si el grafo contiene un ciclo, se usa un orden alternativo (según la 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 conexiones donde target es igual al ID del nodo actual. Por ejemplo, un nodo SQL Transform con dos entradas tendrá una sources que contiene exactamente dos IDs en el orden correcto.

3. arreglo cte_nodes. Cada nodo se escribe como un registro en el cte_nodes arreglo, en orden topológico. Consulte la estructura de cte_nodes más abajo para conocer los detalles de los campos.

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

Claves de nivel superior

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

Clave	Presencia	Descripción
version	Primer comentario configurado en la regla coincidente.	Número de versión del formato. Siempre 2 para las exportaciones actuales.
nombre	Primer comentario configurado en la regla coincidente.	Nombre del flujo de trabajo.
descripción	Primer comentario configurado en la regla coincidente.	Descripción del flujo de trabajo. Puede ser una cadena vacía.
cte_nodes	Primer comentario configurado en la regla coincidente.	Arreglo de registros de nodos en orden topológico. Consulte la estructura de cte_nodes.
edges	Primer comentario configurado en la regla coincidente.	Arreglo de objetos de conexión. Consulte estructura de edges.
output_Nodo_id	Cuando existe un Nodo de salida	El ID del nodo de salida en el flujo de trabajo.
ventana gráfica	Cuando se establece en el flujo de trabajo	Posición y nivel de zoom del lienzo: { x, y, zoom }. Se usa para restaurar el diseño visual al importar.
programación	Cuando la programación está activada	Cronograma de ejecución: { cron, timezone }. El cron predeterminado es 0 0 * * *, la zona horaria predeterminada es UTC.

la estructura de cte_nodes

Cada entrada en el cte_nodes array representa un Nodo en el grafo del flujo de trabajo.

Campo	Descripción
id	Identificador único del Nodo (cadena).
tipo	Tipo de Nodo. Uno de: telemática, negocio, filtro, remuestreo, sql, aritmética, personalizado, salida.
label	Nombre para mostrar que se muestra en el lienzo. Se usa el ID del Nodo si no se define.
descripción	Descripción del Nodo. Puede ser una cadena vacía.
posición	Coordenadas del lienzo como { x, y }.
sources	Lista ordenada de IDs de nodos predecesores, derivada de las aristas del grafo. Vacía para los nodos de origen.
params	Parámetros de configuración del Nodo. Los campos específicos dependen del tipo de Nodo. Consulte la Transformation Builder documentación para ver los detalles de los parámetros por tipo de Nodo.
width, height	Opcional. Dimensiones del lienzo para el Nodo, incluidas solo cuando se configuran explícitamente.

Limpieza de parámetros. El available_tables y available_columns los campos se eliminan de params durante la exportación. Estos campos se completan en tiempo de ejecución cuando 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 agrega un join_spec campo del registro. Esta es un arreglo con un elemento que contiene la configuración de unión:

especificación de unión:
  - type: "left"       # tipo de unión (en minúsculas): left, inner, right, full
    al_condición: "a_node_telematics_1.device_id = a_node_business_1.device_id"

El tipo el valor se toma del Nodo join_type parámetro (convertido a minúsculas) y on_condition se toma de join_condition. Para los Nodos SQL con dos fuentes, la información de unión aparece en ambos params y join_spec.

estructura de edges

El edges arreglo define las conexiones entre los Nodos en el gráfico del flujo de trabajo.

aristas:
  - source: "Nodo-telematics-1"
    destino: "Nodo-sql-1"
  - fuente: "Nodo-business-1"
    destino: "Nodo-sql-1"

Cada arista es un Objeto con dos campos:

Campo	Descripción
fuente	El ID del Nodo en el que se origina la arista.
target	El ID del nodo donde termina la arista.

Los IDs de arista de la interfaz de Builder no se conservan en la exportación. Al importar, se generan automáticamente nuevos IDs de arista.

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 versión: 2 o la clave cte_nodes, el archivo se procesa como versión 2.

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

Importación de la versión 2

El generador recorre el cte_nodes arreglo en orden. Para cada registro:

• El id y tipo 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 sqlnodos de tipo -type, si un join_spec campo está presente en el registro, se asigna a la configuración de unión del nodo.

• El edges el arreglo se analiza en pares origen-destino, y se generan nuevos IDs de arista.

• El ventana gráfica y programación los campos se conservan si están presentes en el YAML.

Importación de la versión 1 (compatibilidad retroactiva)

Los archivos de la versión 1 usan una nodes clave (arreglo o diccionario) y opcionalmente una edges arreglo 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 admitidos son los mismos que en la versión 2: telemática, negocio, filtro, remuestreo, sql, aritmética, personalizado, salida.

• Las conexiones entre Nodos pueden definirse de dos maneras: un arreglo de nivel superior edges arreglo, o una depends_on lista dentro de cada Nodo.

• El entradas y salidas los campos en cada Nodo se normalizan a objetos con { name, type } estructura.

• Si las aristas incluyen sourceHandle o targetHandle identificadores de puerto, la importación ajusta los puertos del Nodo en consecuencia para que se muestren correctamente en la interfaz de Builder.

plantilla de estructura YAML

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

versión: 2
nombre: "workflow_name"
description: "Descripción del flujo de trabajo"

cte_nodes:
  - id: "id-de-nodo-1"
    tipo: telemática    # telemática | negocio | filtro | remuestreo |
                        # SQL | aritmética | personalizado | salida
    label: "Nombre para mostrar del Nodo"
    description: ""
    posición: { x: 100, y: 100 }
    sources: []         # vacío para nodos de origen
    parámetros:
      table_name: "seguimiento_data_core"
      time_column: "device_time"
      columnas: [device_id, device_time, speed]
      filter_condition: ""
      time_window_minutes: ""

  - id: "id-de-Nodo-2"
    tipo: sql
    etiqueta: "Transformación SQL"
    description: ""
    posición: { x: 400, y: 160 }
    fuentes: ["node-id-1", "node-id-3"]   # IDs de predecesores ordenados
    parámetros:
      tipo de unión: LEFT
      condición_de_enlace: "a_node_id_1.device_id = a_node_id_3.device_id"
      seleccionar_columnas: ["a_node_id_1.*", "a_node_id_3.sensor_label"]
    join_spec:                             # agregado para nodos SQL con 2+ fuentes
      - type: "left"
        en_condición: "a_node_id_1.device_id = a_node_id_3.device_id"

    # Campos opcionales por nodo:
    # ancho: 250
    # Altura: 400

aristas:
  - fuente: "node-id-1"
    destino: "node-id-2"
  - fuente: "node-id-3"
    destino: "node-id-2"

# Campos opcionales de nivel superior:
output_node_id: "node-output-1"           # si existe un Nodo de salida
viewport: { x: 0, y: 0, zoom: 1 }        # posición del lienzo al importar
programación: { cron: "0 0 * * *", timezone: "UTC" }  # si la Programación está activada

Ejemplo

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

versión: 2
nombre: enriched_vehicle_metrics
description: "Métricas enriquecidas del vehículo a partir de la telemática y la descripción del sensor"

cte_nodes:
  - id: Nodo-telematics-1
    tipo: telemática
    label: "Datos brutos: telemática"
    description: ""
    posición: { x: 100, y: 100 }
    fuentes: []
    parámetros:
      table_name: inputs
      time_column: device_time
      columnas: [device_id, device_time, value]
      filter_condition: ""
      time_window_minutes: ""

  - id: Nodo-business-1
    tipo: negocio
    etiqueta: "Datos brutos: Negocio"
    description: ""
    position: { x: 100, y: 220 }
    fuentes: []
    parámetros:
      table_name: sensor_description
      columna clave: sensor_id
      columnas: [sensor_id, device_id, sensor_label]

  - id: Nodo-sql-1
    tipo: sql
    etiqueta: "Transformación SQL"
    description: ""
    posición: { x: 400, y: 160 }
    fuentes: [nodo-telematics-1, nodo-business-1]
    parámetros:
      tipo de unión: LEFT
      condición_de_unión: "a_node_telematics_1.device_id = a_node_business_1.device_id"
      select_columns: ["a_node_telematics_1.*", "a_node_business_1.sensor_label"]
    especificación de unión:
      - type: "left"
        al_condición: "a_node_telematics_1.device_id = a_node_business_1.device_id"

  - id: nodo-arithmetic-1
    tipo: aritmético
    label: "Aritmética"
    description: ""
    posición: { x: 700, y: 160 }
    fuentes: [Nodo-sql-1]
    parámetros:
      expresiones:
        - columna: valor
          expresión: "value::numeric"
          expression_alias: value_num

  - id: nodo-output-1
    tipo: salida
    label: "Salida"
    description: ""
    position: { x: 1000, y: 160 }
    fuentes: [nodo-arithmetic-1]
    parámetros:
      nombre de la tabla: enriched_vehicle_metrics
      time_column: device_time
      primary_key: [device_id, device_time]
      modo de escritura: anexar

aristas:
  - { source: node-telematics-1, target: node-sql-1 }
  - { origen: nodo-business-1, destino: nodo-sql-1 }
  - { origen: nodo-sql-1, destino: nodo-arithmetic-1 }
  - { source: node-arithmetic-1, target: node-output-1 }

output_node_id: nodo-output-1
viewport: { x: 0, y: 0, zoom: 1 }
programación: { cron: "0 0 * * *", timezone: "UTC" }

Este flujo de trabajo realiza los siguientes pasos:

1. nodo-telemática-1 lee device_id, device_time, y value columnas de la entradas tabla en la raw_telematics_data esquema.

2. nodo-business-1 lee sensor_id, device_id, y sensor_label de la sensor_description tabla en la raw_business_data esquema.

3. nodo-sql-1 une las dos fuentes por device_id mediante un LEFT JOIN, seleccionando todas las columnas de telemetría además de la sensor_label fuente de negocio.

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

5. nodo-output-1 configura el resultado para que se escriba en la enriched_vehicle_metrics tabla con anexar 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 Builder se conecta a la base de datos. Para nodos SQL con dos fuentes, la información de la unión aparece en ambas params y join_spec.

Próximos pasos

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

• Plantillas: Configuraciones de flujo de trabajo predefinidas que puede importar y adaptar en Transformation Builder.

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