Referencia de expresiones para flujos de datos y grafos de flujo de datos

Esta referencia se aplica tanto a los flujos de datos como a los gráficos de flujo de datos. Ambos usan el mismo lenguaje de expresión para las transformaciones de asignación, filtro y enriquecimiento. Los gráficos de flujo de datos también admiten transformaciones de rama y ventana (acumulado), que se indican cuando corresponda.

Variables posicionales

La matriz de inputs cada regla determina las variables disponibles en .expression La primera entrada se convierte en $1, la segunda se convierte $2en y así sucesivamente.

Si solo se especifica una entrada y no se proporciona ninguna expresión, el valor de esa entrada se copia directamente en la salida.

Operadores

Las expresiones admiten los operadores siguientes, enumerados de mayor a menor prioridad:

El + operador concatena cadenas cuando al menos un operando es una cadena. Use paréntesis para invalidar la precedencia predeterminada.

Ejemplos:

Funciones integradas

Funciones de conversión de unidades

Estas funciones aceptan un único valor numérico y devuelven un valor float.

Escalado y redondeo de funciones

Funciones matemáticas

Estas funciones proceden de la biblioteca matemática integrada.

Funciones de cadena

Funciones de fecha y hora

Las funciones de fecha y hora solo están disponibles en gráficos de flujo de datos. Excepto para parse_timestamp, las funciones que aceptan una marca de tiempo requieren una cadena RFC 3339 . La cadena debe incluir un desplazamiento explícito respecto al Tiempo Universal Coordinado (UTC), como 2026-06-17T12:00:00Z o 2026-06-17T12:00:00-08:00. La Returns columna muestra el tipo de resultado conceptual, que typeof se indica en minúsculas como "float", "int", o "string".

now() lee el reloj del sistema del nodo Kubernetes que alberga la carga de trabajo del flujo de datos cada vez que la función se ejecuta. Las llamadas en la misma expresión pueden devolver valores diferentes. En una regla de acumulación, now() devuelve el momento en que se procesa la ventana, no cuando llega un mensaje de entrada. Para reducir el desfase de reloj entre los nodos del clúster, sincroniza cada nodo con una fuente de tiempo fiable, como un servidor de Protocolo de Tiempo de Red.

Las funciones de calendario y reloj, como day_of_week, hour_of_day, y year_of, utilizan el desplazamiento en la marca de tiempo de entrada. No convierten primero el valor a UTC. Los siguientes ejemplos muestran este comportamiento.

Formato y marcas de tiempo de análisis

Las format_timestamp funciones y parse_timestamp usan strftime patrones. La siguiente tabla enumera los especificadores comunes.

Para todos los especificadores compatibles, consulte la documentación de Chrono strftime.

format_timestamp conserva el desplazamiento de la marca de tiempo de entrada. Por ejemplo, format_timestamp("2026-06-09T14:00:00+02:00", "%Y-%m-%d %H:%M %:z") devuelve "2026-06-09 14:00 +02:00".

parse_timestamp gestiona las entradas en el siguiente orden:

1. Una fecha y hora con un desplazamiento numérico. La función respeta el desplazamiento y normaliza el resultado a UTC.
2. Una fecha y hora sin desfasamiento. La función asume UTC.
3. Una cita sin hora. La función asume medianoche UTC.

Los siguientes ejemplos muestran cómo parse_timestamp gestiona cada tipo de entrada.

Convertir valores de época Unix

Usar from_epoch y to_epoch convertir entre valores de época Unix y marcas de tiempo RFC 3339.

from_epoch acepta valores negativos para fechas anteriores al 1 de enero de 1970. Su salida tiene precisión milisegundos, por lo que convertir microsegundos de época en una marca de tiempo descarta precisión por debajo de un milisegundo. to_epoch tiene en cuenta el desplazamiento UTC de la marca de tiempo y redondea los valores anteriores a 1970 hasta el siguiente número entero inferior para la unidad seleccionada.

Se pueden componer funciones de fecha y hora. Por ejemplo, duration_between($1, now(), "days") calcula la antigüedad en días de una marca de tiempo RFC 3339 proporcionada como la primera entrada de regla. Para leer la hora de una marca de tiempo después de convertirla a UTC, utiliza hour_of_day(from_epoch(to_epoch($1, "micros"), "micros")).

Funciones condicionales y de recopilación

Funciones de agregación (solo transformaciones de ventana)

Estas funciones solo están disponibles en reglas de acumulación dentro de transformaciones de ventana. Cada toma una sola variable posicional.

Para más información sobre el uso de funciones de agregación, consulte Agregado de datos a lo largo del tiempo.

Lógica condicional

Use la función para bifurcar la if lógica dentro de una expresión:

Use () (el valor vacío) en comparaciones para detectar campos que faltan.

Campos de metadatos

Leer y escribir en metadatos de mensaje mediante el $metadata. prefijo en los inputs campos o output de una regla. Las referencias de metadatos van en la ruta de acceso del campo, no en la propia expresión.

Propiedades de metadatos

• Tema: Funciona tanto para MQTT como para Kafka. Contiene la cadena de texto donde se publicó el mensaje. Ejemplo: $metadata.topic.
• Propiedad de usuario: en MQTT, hace referencia a los pares clave-valor de forma libre que puede llevar un mensaje MQTT. Por ejemplo, si el mensaje MQTT se publicó con una propiedad de usuario con la clave "priority" y el valor "high", la $metadata.user_property.priority referencia contiene el valor "high". Las claves de propiedad de usuario pueden ser cadenas arbitrarias y pueden requerir escape: $metadata.user_property."weird key" usa la clave "weird key" (con un espacio).
• Propiedad del sistema: este término se usa para cada propiedad que no es una propiedad de usuario. Actualmente, solo se admite una sola propiedad del sistema: $metadata.system_property.content_type, que lee la propiedad de tipo de contenido del mensaje MQTT (si se establece).
• Encabezado: Este es el equivalente en Kafka de la propiedad de usuario de MQTT. Kafka puede usar cualquier valor binario para una clave, pero los flujos de datos solo admiten claves de cadena UTF-8. Ejemplo: $metadata.header.priority. Esta funcionalidad es similar a las propiedades del usuario.

Lectura de metadatos

Para hacer referencia al tema de origen y una propiedad de usuario en una expresión, enumere como entradas:

Expresión: $1 + "/" + $2

En el ejemplo siguiente, la propiedad topic de MQTT se asigna al campo origin_topic en la salida:

Si la propiedad de usuario priority está presente en el mensaje MQTT, en el ejemplo siguiente se muestra cómo asignarla a un campo de salida:

Escritura en metadatos

Para establecer una propiedad de usuario en el mensaje de salida, use $metadata.user_property.<key> como campo de salida.

Si se establece un campo de metadatos en un valor vacío (()) se quita. En el caso de las propiedades de usuario, se permiten claves duplicadas.

También puede asignar propiedades de metadatos a un encabezado de salida o a una propiedad de usuario. En el ejemplo siguiente, topic del MQTT se asigna al campo origin_topic en la propiedad de usuario de la salida:

Si la carga entrante contiene un campo priority, en el ejemplo siguiente se muestra cómo asignarla a una propiedad de usuario MQTT:

El mismo ejemplo para Kafka:

Los campos de metadatos se admiten en las reglas de asignación, filtro y rama. No están disponibles en las reglas de ventana (acumulación).

Último valor conocido

Use el ? $last sufijo en una entrada para indicar al runtime que recuerde el valor más reciente de ese campo. Si falta el campo en el mensaje actual, se usa en su lugar el último valor conocido.

La ? $last directiva no distingue mayúsculas de minúsculas y admite espacios en blanco flexibles.

El último valor conocido se admite en las reglas de asignación, filtro y rama. No está disponible en las reglas de ventana (acumulado).

Valores predeterminados

Use el ?? <default> sufijo en una entrada para proporcionar un valor de reserva cuando falte el campo. Tipos predeterminados admitidos: entero, float, booleano, cadena y null.

Combinar el último valor conocido y el valor predeterminado

Puede combinar ? $last y ?? <default>. El tiempo de ejecución comprueba primero el mensaje actual, después el último valor conocido y, a continuación, el valor predeterminado. Si usa ?? <default> sin ? $last, el tiempo de ejecución comprueba el mensaje actual y, a continuación, el valor predeterminado directamente.

Los valores predeterminados se admiten en las reglas de asignación, filtro y rama. No están disponibles en las reglas de ventana (acumulación).

Tipos de datos

Los objetos y matrices JSON se conservan as-is cuando los campos se copian sin una expresión, pero no se pueden usar como entradas para la evaluación de expresiones.

Compatibilidad de características por tipo de transformación

El mismo lenguaje de expresiones funciona entre transformadas, pero el resultado de una expresión significa algo diferente en cada una:

¹ Solo disponible en gráficos de flujo de datos. No se admite en las entradas de flujo builtInTransformation de datos.

Notación de puntos y escape

La notación de puntos se usa ampliamente para hacer referencia a campos anidados. Una ruta de acceso de notación de puntos estándar tiene el aspecto de Person.Address.Street.Number.

En un flujo de datos, una ruta de acceso descrita por notación de puntos puede incluir cadenas y algunos caracteres especiales sin necesidad de escape, como Person.Date of Birth.

En otros casos, el escape es necesario, por ejemplo: nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Esta ruta de acceso, entre otros caracteres especiales, contiene puntos dentro del nombre del campo. Si no se escapa, el nombre del campo serviría como separador en la notación de puntos.

Mientras un flujo de datos analiza una ruta de acceso, trata solo dos caracteres como especiales:

• Los puntos (.) actúan como separadores de campo.
• Las comillas dobles, cuando se colocan al principio o al final de un segmento, inician una sección escapada donde los puntos no se tratan como separadores de campo.

Cualquier otro carácter se trata como parte del nombre del campo. Esta flexibilidad es útil en formatos como JSON, donde los nombres de campo pueden ser cadenas arbitrarias.

La definición de ruta de acceso también debe cumplir las reglas del formato de configuración. Cuando se incluye un carácter con significado especial en la ruta de acceso, se requiere una comilla adecuada. Por ejemplo, los nombres de campo que comienzan por dos puntos (como :Person:.:name:) o que comienzan con un número seguido de texto (como 100 celsius.hot) necesitan que las comillas de la configuración se interpreten correctamente como cadenas.

Escapando

La función principal de escape en una ruta de acceso con notación de puntos es dar cabida al uso de puntos que forman parte de nombres de campo en lugar de separadores. Por ejemplo, la ruta de acceso Payload."Tag.10".Value consta de tres segmentos: Payload, Tag.10y Value. Las comillas dobles alrededor Tag.10 impiden que el punto actúe como separador.

Reglas de escape en la notación de puntos

• Escapar cada segmento por separado: si varios segmentos contienen puntos, esos segmentos deben estar entre comillas dobles. También se pueden citar otros segmentos, pero no afecta a la interpretación de la ruta de acceso. Por ejemplo: Payload."Tag.10".Measurements."Vibration.$12".Value

• Cita un segmento solo cuando necesite escapar. Añade comillas dobles alrededor de un segmento solo cuando contenga un punto (u otro carácter que de otro modo se interpretaría erróneamente como separador). No cites un nombre de campo cualquiera.

  Por ejemplo, para un cuerpo nombrado TagName dentro Recordsde :

  Haga lo siguiente	No esto
  Records.TagName	Records."TagName"

  Las comillas extra no ayudan y, en algunas herramientas, como el editor de flujo de datos de experiencia de operaciones, pasan a formar parte del nombre del campo. El mapeo busca entonces un campo nombrado "TagName" (entre comillas incluidas), que no existe, así que nada coincide. Esto se puede detectar en la definición de flujo de datos exportados, donde el nombre aparece entre comillas escapadas, como \"TagName\". Para solucionarlo, elimina las comillas para que el nombre sea simplemente TagName.

• Uso adecuado de comillas dobles: las comillas dobles deben abrir y cerrar un segmento escapado. Las comillas del centro del segmento se consideran parte del nombre del campo. Por ejemplo, la ruta de acceso Payload.He said: "Hello", and waved define dos campos: Payload y He said: "Hello", and waved. Cuando aparece un punto en estas circunstancias, sigue funcionando como separador. Por ejemplo, la ruta de acceso Payload.He said: "No. It is done" se divide en los segmentos Payload, He said: "Noy It is done" (empezando por un espacio).

Algoritmo de segmentación

• Si el primer carácter de un segmento es una comilla, el analizador busca las siguientes comillas. La cadena incluida entre estas comillas se considera un único segmento.
• Si el segmento no comienza con una comilla, el analizador identifica los segmentos buscando el siguiente punto o el final de la ruta de acceso.

Caracteres comodín

Use un carácter comodín (*) en las rutas de acceso de entrada y salida para que coincidan con varios campos a la vez. Esto resulta útil cuando la salida se parece estrechamente a la entrada o cuando necesita aplicar la misma transformación en muchos campos sin enumerar cada uno.

Copiar todos los campos

Para pasar todos los campos sin cambios:

* coincide con cada ruta de acceso de campo de la entrada y la coloca en la misma ruta de acceso de la salida. La parte de la ruta de acceso que * coincide se denomina segmento capturado. En la salida, el segmento capturado reemplaza a *.

Aplanar campos anidados

Para mover campos fuera de un objeto anidado al nivel raíz, coloque el prefijo en la entrada y * en la salida:

Dada esta entrada:

{
  "Sensors": { "Temperature": 72.5, "Pressure": 14.7 },
  "Metadata": { "LineId": "Line-3", "Shift": "A" }
}

La salida aplana ambos objetos:

{
  "Temperature": 72.5,
  "Pressure": 14.7,
  "LineId": "Line-3",
  "Shift": "A"
}

Reestructurar campos

Para mover campos debajo de un nuevo elemento primario, coloque * en la entrada y agregue un prefijo en la salida:

Esto encapsula todos los campos de nivel superior dentro de un Telemetry objeto .

Reglas de selección de ubicación de caracteres comodín

• Solo se permite uno* por ruta de acceso de entrada o salida.
• * debe coincidir con un segmento completo (no un segmento parcial como Sensor*).
• * puede aparecer al principio (*.Value), el medio (Sensors.*.Reading) o el final (Sensors.*) de una ruta de acceso.

Caracteres comodín de entrada múltiple

Cuando una regla tiene varias entradas con caracteres comodín, * debe capturar el mismo segmento en todas las entradas. El tiempo de ejecución resuelve desde * la primera entrada y, a continuación, busca rutas de acceso coincidentes en las otras entradas.

Por ejemplo, para calcular el promedio de lecturas máximas y mínimas para cada sensor:

Dada esta entrada:

{
  "Temperature": { "Max": 85.3, "Min": 62.1 },
  "Pressure": { "Max": 15.2, "Min": 14.1 }
}

Captura * primero, por lo que la regla busca y TemperatureTemperature.Max.Temperature.Min A continuación, captura Pressure y busca Pressure.Max y Pressure.Min. La salida es la siguiente:

{
  "Averaged": { "Temperature": 73.7, "Pressure": 14.65 }
}

Si alguna entrada no se puede resolver para un segmento capturado (por ejemplo, *.Mid.Avg cuando el campo está anidado de forma diferente), se omite ese segmento. Asegúrese de que las rutas de acceso de todas las entradas reflejan la estructura real de los datos.

Invalidación de un carácter comodín para campos específicos

Puede combinar una regla de caracteres comodín con reglas específicas. Las reglas específicas tienen prioridad cuando tienen una cobertura menor (menos segmentos coincidentes con *). Esto se denomina especialización.

La primera regla se aplica a todos los campos. La segunda regla lo invalida solo por Pressure , porque Pressure.Max es más específico que *.Max (cobertura 0 frente a cobertura 1).

Para excluir un campo por completo, use una salida vacía:

Una salida vacía quita el campo del resultado. Esto invalida cualquier regla de caracteres comodín que, de lo contrario, la incluiría.

Varias reglas en las mismas entradas

Si dos reglas tienen la misma cobertura o superior, ambas se aplican. Esto le permite calcular varios valores derivados de las mismas entradas:

Ambas reglas se ejecutan para cada segmento capturado, lo que genera dos campos de salida por sensor.

Caracteres comodín en conjuntos de datos de contextualización

Puede usar caracteres comodín con $context referencias para copiar todos los campos de un conjunto de datos:

Esto copia todos los campos del assetMeta conjunto de datos en la Asset sección de la salida.

Conjuntos de datos de contextualización

Los conjuntos de datos de contextualización permiten que las asignaciones integren datos adicionales de bases de datos externas. Use el $context(datasetName) prefijo para hacer referencia a campos de un conjunto de datos. Por ejemplo, $context(position).BaseSalary lee el BaseSalary campo de un conjunto de datos denominado position.

Para más información sobre cómo configurar conjuntos de datos de contextualización, consulte Enriquecimiento de datos mediante flujos de datos y Enriquecimiento con datos externos en gráficos de flujo de datos.

Contenido relacionado

Si has llegado aquí buscando la sintaxis utilizada en una transformación específica, estos artículos muestran expresiones en contexto:

Para flujos de datos, consulte Mapear datos usando flujos de datos y Filtrar datos en un flujo de datos.