Conector Transform

Descripción General

El conector Transform añade o reemplaza campos de la carga evaluando una lista de reglas. Cada regla produce una clave de salida usando uno de tres tipos de expresión: JSONPath, plantilla Go text/template o un literal estático.

Tipo de Conector: MeddleTransform

Configuración

{
  "type": "MeddleTransform",
  "config": {
    "dropOriginal": false,
    "rules": [
      { "outputKey": "temperature",  "type": "jsonpath", "expression": "$.sensor.temperature" },
      { "outputKey": "summary",      "type": "template", "expression": "{{ .sensor_id }}: {{ .status }}" },
      { "outputKey": "data_source",  "type": "static",   "expression": "edge-gateway-01" }
    ]
  }
}

Parámetros de Configuración

• rules (obligatorio, mínimo 1): Array ordenado de reglas de transformación
• dropOriginal: Cuando es true, sólo se emiten las salidas de las reglas; la carga fuente se descarta. Por defecto false — los campos fuente se conservan y las salidas de las reglas se superponen sobre ellos.

Campos de la Regla

• outputKey (obligatorio): Clave de la carga en la que escribe la regla
• type (obligatorio): jsonpath, template o static
• expression (obligatorio): Expresión específica del tipo

Reglas JSONPath

type: "jsonpath" evalúa una expresión JSONPath contra la carga (serializada a JSON internamente). Úsalo para extraer valores anidados.

{ "outputKey": "first_metric", "type": "jsonpath", "expression": "$.metrics[0].value" }

Patrones comunes:

$.field                    – campo de nivel superior
$.sensor.temperature       – campo anidado
$.metrics[0].value         – primer elemento del array
$.metrics[*].name          – proyección de array

Reglas Template

type: "template" ejecuta una plantilla Go text/template contra la carga. Los campos de la carga son accesibles como {{ .field }}. El resultado es siempre una cadena.

{ "outputKey": "label", "type": "template", "expression": "{{ .device }}/{{ .channel }}" }

{{ .temperature }}                                              – sustitución
{{ if gt .pressure 100.0 }}HIGH{{ else }}OK{{ end }}            – condicional
Sensor {{ .id }} reports {{ printf "%.2f" .value }}             – formato

Reglas Static

type: "static" escribe la cadena literal expression en outputKey en cada carga. Úsalo para etiquetas, marcadores de origen o IDs de pipeline.

{ "outputKey": "source", "type": "static", "expression": "field-gateway" }

Drop Original

Cuando dropOriginal: true, el conector emite sólo las salidas de las reglas y descarta cada campo de entrada. Úsalo para proyectar una carga a una forma mínima.

{
  "type": "MeddleTransform",
  "config": {
    "dropOriginal": true,
    "rules": [
      { "outputKey": "ts",    "type": "jsonpath", "expression": "$.timestamp" },
      { "outputKey": "value", "type": "jsonpath", "expression": "$.metrics[0].value" }
    ]
  }
}

Casos de Uso

1. Extraer un campo anidado al nivel superior para conectores descendentes
2. Construir una cadena de resumen legible por humanos para notificaciones
3. Etiquetar cargas con un identificador de pipeline o fuente
4. Reformar una carga de protocolo verbosa en un esquema descendente más esbelto

Ejemplo: Tipos de Regla Mixtos

{
  "type": "MeddleTransform",
  "config": {
    "dropOriginal": false,
    "rules": [
      { "outputKey": "device_id",   "type": "jsonpath", "expression": "$.metadata.deviceId" },
      { "outputKey": "temperature", "type": "jsonpath", "expression": "$.readings.temp" },
      { "outputKey": "alert_text",  "type": "template", "expression": "Device {{ .device_id }} at {{ .temperature }}°C" },
      { "outputKey": "env",         "type": "static",   "expression": "production" }
    ]
  }
}

Ten en cuenta que alert_text referencia device_id — las salidas de reglas anteriores no son visibles para reglas posteriores dentro del mismo paso de Transform, por lo que {{ .device_id }} se refiere a la clave de la carga original sólo si ya existe aguas arriba. Encadena dos conectores Transform cuando necesites composición por etapas.

Mejores Prácticas

• Usa JSONPath cuando extraigas valores estructurados; usa template para composición de cadenas; usa static para constantes
• Prefiere Transform sobre Script cuando la lógica sea sólo extracción o formato — es más rápido y fácil de auditar
• Usa dropOriginal: true para forzar un esquema descendente estricto
• Valida las expresiones JSONPath por adelantado — las rutas inválidas afloran como errores en tiempo de ejecución en el canal de errores

Conectores Relacionados

• Reshape - Renombrado directo de claves
• Script - Lua en sandbox para lógica compleja
• Filter - Lista blanca/lista negra de claves
• Validation - Forzar tipos y rangos de campos