> 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/es/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md). # Referencia de YAML del flujo de trabajo El formato YAML del flujo de trabajo captura los grafos de nodos, parámetros y aristas de Transformation Builder para exportar, importar y compartir 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. {% columns %} {% column %} #### **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. {% endcolumn %} {% column %} #### **Importar** Acepta tanto la versión 2 (el formato actual) como la versión 1 (un formato anterior con `depends_on`conexiones basadas en nodos). Use la **Importar** función en el Builder y seleccione un `.yaml` o `.yml` archivo. {% endcolumn %} {% endcolumns %} ## 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](#cte_nodes-structure) 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](#cte_nodes-structure). | | `edges` | Primer comentario configurado en la regla coincidente. | Arreglo de objetos de conexión. Consulte [estructura de edges](#edges-structure). | | `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](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder.md) 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: ```yaml 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. ```yaml 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 `sql`nodos 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: {% code expandable="true" %} ```yaml 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 ``` {% endcode %} ### 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. {% code expandable="true" %} ```yaml 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" } ``` {% endcode %} 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. {% hint style="info" %} 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`. {% endhint %} ## Próximos pasos * [**Transformation Builder**](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder.md): Aprenda a diseñar flujos de trabajo usando la interfaz visual. * [**Plantillas**](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Configuraciones de flujo de trabajo predefinidas que puede importar y adaptar en Transformation Builder. * [**Capa de transformación**](/docs/analytics/es/iot-query/schema-overview/transformation-layer.md): Entienda cómo se organizan los datos procesados en esquemas y cómo consultarlos. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/analytics/es/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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.