> 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.md). # Transformation Builder Cree transformaciones personalizadas de IoT Query con un editor visual de flujos de trabajo. Configure nodos SQL, previsualice resultados, valide flujos de trabajo y programe ejecuciones {% hint style="info" %} #### ¡Próximamente! Transformation Builder se encuentra actualmente en desarrollo. La descripción de la funcionalidad en esta página refleja la funcionalidad prevista. Los detalles de implementación pueden evolucionar antes del lanzamiento final. Si le interesa el acceso anticipado o tiene preguntas, comuníquese con . {% endhint %} ## Qué es Transformation Builder **Transformation Builder** es una herramienta visual para diseñar flujos de trabajo de transformación de datos sin necesidad de desarrollar y mantener pipelines de datos complejos. Usted organiza la lógica de procesamiento como un grafo, donde cada paso se representa mediante un bloque independiente (nodo), y la herramienta compila su grafo en SQL ejecutable. Transformation Builder está diseñado para analistas, especialistas en BI y cualquier persona con conocimientos básicos de SQL que quiera controlar de forma independiente la lógica de preparación de datos. Le ayuda a responder las preguntas clave de la preparación de datos: de dónde provienen los datos, cómo se combinan, qué filtros y transformaciones se aplican, cómo se agregan las series temporales y en qué formato deben aparecer los datos en la [Capa de transformación](/docs/analytics/es/iot-query/schema-overview/transformation-layer.md). Transformation Builder no es un orquestador ETL completo ni una plataforma de datos. Es un diseñador de flujos de trabajo enfocado que compila su grafo de nodos en una consulta SQL y una función de base de datos programada. Las plantillas de flujo de trabajo predefinidas para transformaciones comunes de Navixy están disponibles en la [Plantillas](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md) página. ## Cómo funciona Un flujo de trabajo en Transformation Builder es un grafo dirigido de nodos organizado desde las fuentes de datos hasta la salida:
workflow graph example showing sources, transformations, and output

Fuentes de datos brutos → Nodos de transformación → Salida

Cada nodo corresponde a un paso lógico de procesamiento. Usted puede combinar varias fuentes en un solo nodo de transformación, y el resultado de un nodo puede alimentar varios nodos descendentes. El grafo le ofrece una representación visual clara de todo el recorrido de los datos, desde las tablas de origen hasta la entidad analítica de destino. Builder compila su grafo en una sola consulta SQL usando expresiones de tabla comunes (CTE). Cada nodo se convierte en una CTE en la consulta final. Este enfoque de compilación significa que Builder no escribe datos directamente en la base de datos. En cambio, genera una configuración que ejecuta el procesamiento real de los datos según una programación. {% hint style="warning" %} Los datos del grafo deben fluir en una sola dirección. No se permiten ciclos. Si Builder detecta un ciclo, devuelve un error de validación. {% endhint %} ### Conexión a la base de datos Antes de empezar a crear un flujo de trabajo, necesita conectarse a su base de datos PostgreSQL. Sin una conexión activa, la vista previa de datos y el descubrimiento de tablas no están disponibles. El panel de conexión le permite especificar su [URL de conexión](/docs/analytics/es/iot-query/connection-setup.md#connection-string-format), conectarse o desconectarse, y ver el número de tablas encontradas en cada categoría. Builder usa dos esquemas en su base de datos: * `raw_telematics_data` para datos de telemática y datos del sensor del dispositivo * `raw_business_data` para datos de referencia del negocio (Gestión de vehículos, empleados, geocercas y entidades similares) Una vez conectado, Builder descubre automáticamente las tablas y columnas disponibles, que luego puede seleccionar al configurar los nodos de fuente de datos.
connection panel showing URL input and discovered table counts
### Nodos de fuente de datos Los nodos de fuente de datos definen de dónde lee datos su flujo de trabajo. Cada nodo de origen corresponde a una tabla de la capa de datos brutos.
Datos brutos: Telemática Este nodo carga datos de series temporales desde la `raw_telematics_data` esquema. | Parámetro | Descripción | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Nombre de la tabla** | Seleccione de la lista de tablas descubiertas cuando se conectó a la base de datos. | | **Columna de tiempo** | La columna de marca de tiempo utilizada para ordenar y aplicar filtros basados en el tiempo. El valor predeterminado es `device_time`. | | **Columnas** | Lista de columnas específicas que se incluirán, o `*` para seleccionar todas las columnas. | | **Condición de filtro** | SQL opcional `WHERE` condición aplicada directamente a la consulta de origen. | | **Minutos de ventana temporal** | Límite de tiempo opcional (en minutos) para restringir la ventana de datos en SQL. Déjelo vacío para no tener límite. | Cada nodo de Datos brutos: Telemática lee exactamente de una tabla. Para usar datos de varias tablas, agregue un nodo separado para cada tabla.
Datos brutos: Negocio Este Nodo carga datos de referencia desde la `raw_business_data` esquema. Las tablas típicas incluyen `objetos`, `Gestión de vehículos`, `dispositivos`, y `sensor_description`. | Parámetro | Descripción | | ---------------------- | ------------------------------------------------------------------------------------------ | | **Nombre de la tabla** | Seleccione de la lista de tablas de negocio detectadas. | | **Columna clave** | La columna clave de esta tabla (por ejemplo, `id de objeto` o `sensor_id`). | | **Columnas** | Lista de columnas específicas que se incluirán, o `*` para seleccionar todas las columnas. | Datos brutos: Los nodos de negocio se usan principalmente como la segunda entrada para el nodo SQL Transform, lo que le permite combinar datos de referencia con series temporales de telemática.
### Nodos de transformación Los nodos de transformación definen qué sucede con sus datos después de que se cargan desde las fuentes. Cada tipo de transformación maneja un patrón de procesamiento específico.
Transformación SQL Combina datos de exactamente dos nodos de origen utilizando SQL `JOIN` operación. | Parámetro | Descripción | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo de unión** | El tipo de unión: `INNER`, `LEFT`, `RIGHT`, o `FULL` (unión externa completa). | | **Condición de unión** | La condición para hacer coincidir filas entre las dos entradas (por ejemplo, hacer coincidir en `device_id`). | | **Seleccionar columnas** | Lista de columnas a incluir en la salida. Admite notación de prefijo como `source.*` para seleccionar todas las columnas de una entrada específica. | La transformación SQL requiere exactamente dos entradas. Las entradas pueden ser cualquier combinación de nodos de Fuente de datos o salidas de otros nodos de transformación.
Filtro Filtra los datos por intervalo de tiempo y condiciones personalizadas. Todas las condiciones se ejecutan en la base de datos como parte de la `WHERE` cláusula (filtrado pushdown). | Parámetro | Descripción | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | **Columna de tiempo** | La columna de marca de tiempo que se usará para el filtrado basado en tiempo. El valor predeterminado es `device_time`. | | **Inicio / fin del rango de tiempo** | Límites inicial y final para el filtro de tiempo. | | **Condiciones dinámicas** | Una lista de condiciones SQL combinadas con `AND`. Úselas para aplicar un filtrado adicional más allá del rango de tiempo. |
Remuestreo Agrega datos de series temporales en intervalos de tiempo fijos. Esto es útil para convertir puntos de datos de alta frecuencia en estadísticas resumidas sobre períodos regulares. | Parámetro | Descripción | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Columna de tiempo** | La columna de marca de tiempo que se usará para agrupar por intervalos. El valor predeterminado es `device_time`. | | **Intervalo** | El intervalo de agregación: `1 min`, `5 min`, `15 min`, `1 hora`, o `1 día`. | | **Agrupar por** | Columnas adicionales para agrupar por (además del intervalo de tiempo). | | **Agregaciones** | Una lista de pares de columna y método que define cómo se agrega cada columna. Métodos disponibles: `promedio`, `suma`, `mínimo`, `máximo`, `primero`, `último`, `conteo`. |
Aritmética Agrega o reemplaza columnas usando expresiones SQL. Use este nodo para crear columnas calculadas a partir de los datos existentes. | Parámetro | Descripción | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Expresiones** | Una lista de definiciones de expresiones. Cada entrada incluye una columna de origen opcional, una expresión SQL y un alias de salida obligatorio. | Por ejemplo, para convertir un valor de velocidad, usted podría establecer la columna de origen en `velocidad`, la expresión en `speed * 1.2`, y el alias en `speed_adjusted`. El alias es obligatorio para cada expresión.
SQL personalizado Proporciona una entrada SQL de forma libre para lógica compleja que los otros tipos de Nodo no pueden expresar. Úselo cuando necesite control total sobre la consulta. | Parámetro | Descripción | | --------------------- | --------------------------------------------------------------------------------------------- | | **SQL personalizado** | A `SELECT` consulta en la que los nodos ascendentes son accesibles mediante sus alias de CTE. | Los alias del Nodo de origen siguen el patrón `a_` (por ejemplo, `a_nodo_1`, `a_filter_1`). Los identificadores de Nodo se normalizan a identificadores SQL válidos, con los espacios y caracteres especiales reemplazados por guiones bajos. Los nodos SQL personalizados aceptan una o dos entradas. Su consulta puede hacer referencia a los CTE correspondientes mediante sus alias.
### Configuración de salida
Salida El **Salida** Nodo define cómo se deben escribir los resultados de su transformación en la capa de transformación. Especifica los metadatos de la tabla de destino que el entorno de ejecución externo usa para almacenar los datos procesados. | Parámetro | Descripción | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Nombre de la tabla** | El nombre de la tabla de destino en la `processed_custom_data` esquema. | | **Columna de tiempo** | La columna de marca de tiempo en los datos de salida (por ejemplo, `device_time`). | | **Particionar por** | Una expresión de particionamiento para organizar los datos almacenados (por ejemplo, `DATE(device_time)`). | | **Clave primaria** | Una lista de columnas que identifican de forma única cada fila (por ejemplo, `[device_id, device_time]`). | | **Modo de escritura** | Cómo se escriben los datos en la tabla de destino: `anexar` (agregar nuevas filas), `sobrescribir` (reemplazar los datos existentes), o `upsert` (actualizar filas existentes, insertar nuevas). |
## Crear un flujo de trabajo Un flujo de trabajo típico sigue estos pasos: {% stepper %} {% step %} **Abrir Transformation Builder** Abra la interfaz de Transformation Builder. {% endstep %} {% step %} **Conectarse a su base de datos** Ingrese la URL de conexión a su PostgreSQL y establezca la conexión. El Builder detecta automáticamente las tablas y columnas disponibles. {% endstep %} {% step %} **Agregar nodos de fuente de datos** Agregue un [**Datos brutos: Telemática**](#raw-data-telematics) nodo y seleccione la tabla y las columnas con las que desea trabajar. Si necesita datos de referencia (por ejemplo, detalles del vehículo o descripciones de sensores), agregue un [**Datos brutos: Negocio**](#raw-data-business) nodo también. {% endstep %} {% step %} **Agregar nodos de transformación** Inserte los nodos de transformación que su flujo de trabajo requiera: * [**Transformación SQL**](#sql-transform) para unir datos * [**Filtro**](#filter) para acotar los resultados * [**Remuestreo**](#resampling) para agregar series temporales * [**Aritmética**](#arithmetic) para agregar columnas calculadas * [**SQL personalizado**](#custom-sql) para lógica compleja. {% endstep %} {% step %} **Configurar el nodo de salida** Agregue [Salida](#output) el nodo y configure el nombre de la tabla de destino, las columnas de clave primaria y el modo de escritura de su entidad analítica. {% endstep %} {% step %} **Conectar nodos** Dibuje aristas entre los nodos para definir el flujo de datos. Conecte los nodos fuente a los nodos de transformación y los nodos de transformación al nodo de salida. El flujo de datos va de izquierda a derecha, desde las fuentes hasta la salida. {% endstep %} {% step %} **Revisar y corregir errores** Revise las sugerencias de validación en busca de cualquier problema de configuración. Corrija los errores en los parámetros del nodo o en la estructura del grafo según sea necesario. {% endstep %} {% step %} **Vista previa de resultados** Haga clic en **Ejecutar** para ejecutar una vista previa de su flujo de trabajo. El Builder compila el grafo en SQL y lo ejecuta contra su base de datos, devolviendo hasta 100 filas para que pueda verificar la salida. {% hint style="info" %} **Exportar** Puede exportar su flujo de trabajo completado como un archivo YAML para su ejecución en tiempo de ejecución o para compartirlo con colegas. Consulte [Referencia de YAML del flujo de trabajo](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md) para obtener detalles del formato. {% endhint %} {% endstep %} {% step %} #### Programar la ejecución Haga clic en **Programar** para abrir el cuadro de diálogo de configuración, donde puede determinar la hora exacta y la frecuencia de ejecución del flujo de trabajo. A la hora establecida, una función en la base de datos activará el flujo de trabajo y guardará su resultado en la capa de transformación. {% endstep %} {% endstepper %}
completed workflow graph with all node types connected

Ejemplo completo del flujo de transformación

### Vista previa de resultados Después de que haga clic en **Ejecutar** en la barra de herramientas, el Builder compila el grafo de su flujo de trabajo en una sola consulta SQL con CTE y la ejecuta en la base de datos PostgreSQL conectada. Los resultados aparecen en el panel inferior. **En una ejecución exitosa**, el panel muestra: * Una tabla de resultados que muestra hasta 100 filas de datos de salida * La consulta SQL ejecutada (la consulta CTE completa generada por el compilador) * Cantidad de filas, cantidad de columnas y tiempo de ejecución * Opción para exportar el resultado a CSV **En caso de error de ejecución**, el panel muestra: * Un mensaje de error que describe qué salió mal * La consulta SQL ejecutada (si la compilación tuvo éxito) * Detalles del error de la base de datos (si el error ocurrió durante la ejecución de la consulta) {% hint style="warning" %} La vista previa de resultados requiere una conexión activa a PostgreSQL. Sin una conexión, la vista previa devuelve un resultado vacío sin ejecutar SQL. La vista previa siempre usa datos reales de su base de datos, no datos simulados. {% endhint %}
Results preview panel showing successful execution with result table and SQL

Resultado del flujo ejecutado

## Validación y compilación El Builder valida su flujo de trabajo en dos niveles. 1. **Validación del grafo** comprueba la estructura general de su flujo de trabajo. El grafo debe ser un grafo acíclico dirigido (DAG) válido, lo que significa que los datos fluyen en una sola dirección, sin ciclos. Si el Builder detecta un ciclo, devuelve un error y resalta los nodos afectados. 2. **Validación de Nodo** comprueba la configuración de cada Nodo de manera individual. El Builder verifica que los campos obligatorios estén completos, que las columnas referenciadas existan en la salida del Nodo anterior y que los parámetros del Nodo sean coherentes con su tipo (por ejemplo, SQL Transform debe tener exactamente dos entradas). Durante la compilación, el Builder convierte su grafo en una sola consulta SQL. Cada Nodo se convierte en una CTE con el alias `a_`. Los Nodos se ordenan topológicamente para que cada CTE pueda referenciar las salidas de sus Nodos predecesores. Si la compilación falla debido a un error de configuración o a una estructura de grafo no válida, el Builder devuelve los detalles del error junto con cualquier SQL parcial que haya podido generar. ## Exportación ### Exportación e importación de YAML Puede exportar un flujo de trabajo completo como un archivo YAML usando el **Exportar** botón de la barra de herramientas. El archivo exportado contiene la definición completa del flujo de trabajo en formato de versión 2, incluidas todas las configuraciones de los Nodos, las aristas del grafo y las posiciones del diseño. Para cargar un flujo de trabajo guardado previamente, use la **Importar** y seleccione un `.yaml` o `.yml` archivo. Para la documentación completa del formato, consulte la [Referencia de YAML del flujo de trabajo](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md). ## Limitaciones actuales Transformation Builder se encuentra actualmente en su versión inicial y se aplican varias restricciones: * **La vista previa requiere una conexión activa a PostgreSQL.** Sin una conexión, no puede obtener una vista previa de los resultados. La vista previa se limita a 100 filas. * **El grafo debe estar libre de ciclos.** Los datos fluyen en una sola dirección, de las fuentes a la salida. * **Sin motor de ejecución integrado.** El Builder genera la configuración y el SQL para su ejecución en tiempo de ejecución externa. No procesa ni almacena datos por sí mismo. * **Solo procesamiento por lotes.** No se admite el procesamiento continuo de datos. ## Próximos pasos * [**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): Aprenda cómo la capa de Transformación organiza los datos procesados en esquemas y cómo consultarlos. * [**Referencia de YAML del flujo de trabajo**](/docs/analytics/es/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md): Revise la Especificación completa del formato de exportación e importación YAML. * [**Capa de Datos brutos**](/docs/analytics/es/iot-query/schema-overview/bronze-layer.md): Explore los esquemas de origen (`raw_telematics_data` y `raw_business_data`) que proporcionan datos de entrada para sus flujos de trabajo. --- # 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.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.