Références d’expressions pour les flux de données et les graphiques de flux de données

Cette référence s’applique aux flux de données et aux graphiques de flux de données. Les deux utilisent le même langage d’expression pour les transformations de mappage, de filtre et d’enrichissement. Les graphiques de flux de données prennent également en charge les transformations de branche et de fenêtre (accumulation), qui sont notées le cas échéant.

Variables positionnelles

Le tableau de inputs chaque règle détermine les variables disponibles dans le expression. La première entrée devient $1, la seconde devient $2, et ainsi de suite.

Si une seule entrée est spécifiée et qu’aucune expression n’est fournie, la valeur à cette entrée est copiée directement dans la sortie.

Opérateurs

Les expressions prennent en charge les opérateurs suivants, répertoriés de la priorité la plus élevée à la plus faible :

L’opérateur + concatène des chaînes quand au moins un opérande est une chaîne. Utilisez des parenthèses pour remplacer la priorité par défaut.

Exemples :

Fonctions intégrées

Fonctions de conversion d’unités

Ces fonctions acceptent une valeur numérique unique et retournent un float.

Fonctions de mise à l’échelle et d’arrondi

Fonctions mathématiques

Ces fonctions proviennent de la bibliothèque mathématique intégrée.

Fonctions de chaîne

Fonctions de date et d’heure

Les fonctions de date et d’heure ne sont disponibles que dans les graphiques de flux de données. Sauf pour parse_timestamp, les fonctions qui acceptent un horodatage nécessitent une chaîne RFC 3339 . La chaîne doit inclure un décalage explicite par rapport au temps universel coordonné (UTC), tel que 2026-06-17T12:00:00Z ou 2026-06-17T12:00:00-08:00. La Returns colonne liste le type de résultat conceptuel, qui typeof indique en minuscules , "float""int", ou "string".

now() lit l’horloge système du nœud Kubernetes qui héberge la charge de travail du flux de données à chaque exécution de la fonction. Les appels dans la même expression peuvent retourner des valeurs différentes. Dans une règle d’accumulation, elle now() renvoie le moment où la fenêtre est traitée, et non l’arrivée d’un message d’entrée. Pour réduire le décalage d’horloge entre les nœuds du cluster, synchronisez chaque horloge avec une source d’heure fiable, telle qu’un serveur Network Time Protocol.

Les fonctions de calendrier et d’horloge, telles que day_of_week, hour_of_day, et year_of, utilisent le décalage dans l’horodatage d’entrée. Ils ne convertissent pas d’abord la valeur en UTC. Les exemples suivants montrent ce comportement.

Formatage et horodatages d’analyse

Les format_timestamp fonctions et parse_timestamp utilisent strftime des motifs. Le tableau suivant liste les spécificateurs courants.

Pour tous les spécificateurs pris en charge, voir la documentation Chrono strftime.

format_timestamp préserve le décalage temporel de l’entrée. Par exemple, format_timestamp("2026-06-09T14:00:00+02:00", "%Y-%m-%d %H:%M %:z") retourne "2026-06-09 14:00 +02:00".

parse_timestamp gère les entrées dans l’ordre suivant :

1. Une date et une heure avec un décalage numérique. La fonction respecte le décalage et normalise le résultat vers UTC.
2. Une date et une heure sans décalage. La fonction suppose l’UTC.
3. Un rendez-vous sans heure. La fonction suppose minuit UTC.

Les exemples suivants montrent comment parse_timestamp chaque type d’entrée est gérée.

Convertir les valeurs d’époque Unix

Utilisez from_epoch et to_epoch pour convertir entre les valeurs d’époque Unix et les horodatages RFC 3339.

from_epoch accepte les valeurs négatives pour les dates antérieures au 1er janvier 1970. Sa sortie a une précision milliseconde, donc convertir les microsecondes d’époque en horodatage élimine la précision inférieure à une milliseconde. to_epoch prend en compte le décalage UTC de l’horodatage et arrondi les valeurs antérieures à 1970 jusqu’à l’entier inférieur suivant pour l’unité sélectionnée.

Des fonctions de date et d’heure peuvent être rédigées. Par exemple, duration_between($1, now(), "days") calcule l’âge en jours d’un horodatage RFC 3339 fourni comme première entrée de règle. Pour lire l’heure d’un horodatage après l’avoir converti en UTC, utilisez hour_of_day(from_epoch(to_epoch($1, "micros"), "micros")).

Fonctions conditionnelles et de collection

Fonctions d’agrégation (transformations de fenêtre uniquement)

Ces fonctions sont disponibles uniquement dans les règles d’accumulation dans les transformations de fenêtre. Chacun prend une variable positionnelle unique.

Pour plus d’informations sur l’utilisation des fonctions d’agrégation, consultez Données agrégées au fil du temps.

Logique conditionnelle

Utilisez la fonction pour brancher la if logique au sein d’une expression :

Utilisez () (la valeur vide) dans les comparaisons pour détecter les champs manquants.

Champs de métadonnées

Lisez et écrivez des métadonnées de message à l’aide du $metadata. préfixe dans le inputs ou output les champs d’une règle. Les références de métadonnées vont dans le chemin du champ, et non dans l’expression elle-même.

Propriétés des métadonnées

• Sujet : fonctionne à la fois pour MQTT et Kafka. Elle contient la chaîne dans laquelle le message a été publié. Exemple : $metadata.topic.
• Propriété utilisateur : dans MQTT, cela fait référence aux paires clé/valeur de forme libre qu’un message MQTT peut porter. Par exemple, si le message MQTT a été publié avec une propriété utilisateur avec la clé « priority » et la valeur « high », la $metadata.user_property.priority référence contient la valeur « high ». Les clés des propriétés utilisateur peuvent être des chaînes arbitraires et nécessiter d'être échappées : $metadata.user_property."weird key" utilise la clé « clé étrange » (avec un espace).
• Propriété système : ce terme est utilisé pour chaque propriété qui n’est pas une propriété utilisateur. Actuellement, une seule propriété système est prise en charge : $metadata.system_property.content_type, qui lit la propriété de type de contenu du message MQTT (si définie).
• En-tête : il s’agit de l’équivalent Kafka de la propriété utilisateur MQTT. Kafka peut utiliser n’importe quelle valeur binaire pour une clé, mais les flux de données prend uniquement en charge les clés de chaîne UTF-8. Exemple : $metadata.header.priority. Cette fonctionnalité est similaire aux propriétés utilisateur.

Lecture à partir des métadonnées

Pour référencer la rubrique source et une propriété utilisateur dans une expression, répertoriez-les en tant qu’entrées :

Expression : $1 + "/" + $2

Dans l’exemple suivant, la propriété topic MQTT est mappée au champ origin_topic dans la sortie :

Si la propriété utilisateur priority est présente dans le message MQTT, l’exemple suivant montre comment la mapper à un champ de sortie :

Écrire dans les métadonnées

Pour définir une propriété utilisateur sur le message de sortie, utilisez-la $metadata.user_property.<key> comme champ de sortie.

La définition d’un champ de métadonnées sur une valeur vide (()) la supprime. Pour les propriétés utilisateur, les clés en double sont autorisées.

Vous pouvez également mapper les propriétés de métadonnées à un en-tête de sortie ou à une propriété utilisateur. Dans l’exemple suivant, le topic MQTT est mappé au champ origin_topic dans la propriété utilisateur de la sortie :

Si la charge utile entrante contient un champ priority, l’exemple suivant montre comment le mapper à une propriété utilisateur MQTT :

Le même exemple pour Kafka :

Les champs de métadonnées sont pris en charge dans les règles de mappage, de filtre et de branche. Ils ne sont pas disponibles dans les règles de fenêtre (accumulation).

Dernière valeur connue

Utilisez le ? $last suffixe sur une entrée pour indiquer au runtime de mémoriser la valeur la plus récente pour ce champ. Si le champ est manquant dans le message actuel, la dernière valeur connue est utilisée à la place.

La directive ne respecte pas la ? $last casse et prend en charge les espaces blancs flexibles.

La dernière valeur connue est prise en charge dans les règles de carte, de filtre et de branche. Il n’est pas disponible dans les règles de fenêtre (accumulation).

Valeurs par défaut

Utilisez le ?? <default> suffixe sur une entrée pour fournir une valeur de secours lorsque le champ est manquant. Types par défaut pris en charge : entier, float, booléen, chaîne et null.

Combiner la dernière valeur connue et la valeur par défaut

Vous pouvez combiner ? $last et ?? <default>. Le runtime vérifie d’abord le message actuel, puis la dernière valeur connue, puis la valeur par défaut. Si vous utilisez ?? <default> sans ? $last, le runtime vérifie le message actuel, puis la valeur par défaut directement.

Les valeurs par défaut sont prises en charge dans les règles de carte, de filtre et de branche. Ils ne sont pas disponibles dans les règles de fenêtre (accumulation).

Types de données

Les objets et tableaux JSON sont conservés as-is lorsque les champs sont copiés sans expression, mais ils ne peuvent pas être utilisés comme entrées pour l’évaluation d’expression.

Prise en charge des fonctionnalités par type de transformation

Le même langage d’expression fonctionne à travers les transformations, mais le résultat d’une expression signifie quelque chose de différent dans chacune d’elles :

¹ Disponible uniquement dans les graphiques de flux de données. Non pris en charge dans les entrées de flux de builtInTransformation données.

Notation par points et échappement

La notation par points est largement utilisée pour référencer les champs imbriqués. Un chemin de notation par points standard ressemble Person.Address.Street.Numberà .

Dans un flux de données, un chemin décrit par la notation par points peut inclure des chaînes et certains caractères spéciaux sans avoir besoin d’échappement, comme Person.Date of Birth.

Dans d’autres cas, l’échappement est nécessaire, par exemple : nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Ce chemin d’accès, entre autres caractères spéciaux, contient des points dans le nom du champ. Sans échappement, le nom du champ servirait de séparateur dans la notation par points elle-même.

Lorsqu’un flux de données analyse un chemin d’accès, il traite uniquement deux caractères comme spéciaux :

• Les points (.) agissent en tant que séparateurs de champs.
• Les guillemets doubles, placés au début ou à la fin d’un segment, ouvrent une section échappée où les points ne sont pas traités comme séparateurs de champ.

Tous les autres caractères sont traités dans le cadre du nom du champ. Cette flexibilité est utile dans les formats tels que JSON, où les noms des champs peuvent être des chaînes arbitraires.

La définition du chemin d’accès doit également respecter les règles du format de configuration. Lorsqu’un caractère avec une signification spéciale est inclus dans le chemin d’accès, un guillemet approprié est requis. Par exemple, les noms de champs qui commencent par un signe deux-points (comme :Person:.:name:) ou qui commencent par un nombre suivi de texte (comme 100 celsius.hot) doivent être interprétés correctement en tant que chaînes dans la configuration.

Échappement

La fonction principale de l’échappement dans un chemin d’accès noté par points consiste à prendre en charge l’utilisation de points qui font partie des noms de champs plutôt que des séparateurs. Par exemple, le chemin Payload."Tag.10".Value se compose de trois segments : Payload, Tag.10et Value. Les guillemets doubles autour Tag.10 empêchent le point d’agir comme séparateur.

Règles d’échappement en notation par points

• Échappement de chaque segment séparément : si plusieurs segments contiennent des points, ces segments doivent être placés entre guillemets doubles. D’autres segments peuvent également être cités, mais cela n’affecte pas l’interprétation du chemin d’accès. Par exemple : Payload."Tag.10".Measurements."Vibration.$12".Value

• Citez un segment uniquement lorsqu’il faut s’échapper. Ajoutez des guillemets doubles autour d’un segment uniquement lorsqu’il contient un point (ou un autre caractère qui serait autrement mal interprété comme un séparateur). Ne citez pas un nom de domaine ordinaire.

  Par exemple, pour un corps nommé TagName à l’intérieur Recordsde :

  Procédez comme suit	Pas ça
  Records.TagName	Records."TagName"

  Les guillemets supplémentaires n’aident pas, et dans certains outils, comme l’éditeur de flux de données d’expérience des opérations, ils deviennent partie intégrante du nom du champ. La correspondance cherche ensuite un champ nommé "TagName" (guillemets inclus), qui n’existe pas, donc rien ne correspond. Vous pouvez repérer cela dans la définition du flux de données exporté, où le nom apparaît avec des guillemets échappés, comme \"TagName\". Pour corriger cela, supprimez les guillemets pour que le nom soit simplement TagName.

• Utilisation appropriée de guillemets doubles : les guillemets doubles doivent ouvrir et fermer un segment d’échappement. Les guillemets au milieu du segment sont considérés comme faisant partie du nom du champ. Par exemple, le chemin Payload.He said: "Hello", and waved définit deux champs : Payload et He said: "Hello", and waved. Lorsqu’un point apparaît dans ces circonstances, il continue de servir de séparateur. Par exemple, le chemin d’accès Payload.He said: "No. It is done" est divisé en segments Payload, He said: "Noet It is done" (à partir d’un espace).

Algorithme de segmentation

• Si le premier caractère d’un segment est un guillemet, l’analyseur recherche le guillemet suivant. La chaîne placée entre ces guillemets est considérée comme un segment unique.
• Si le segment ne commence pas par un guillemet, le parseur identifie les segments en recherchant le point final suivant ou la fin du chemin.

Caractères génériques

Utilisez un caractère générique (*) dans les chemins d’entrée et de sortie pour correspondre à plusieurs champs à la fois. Cela est utile lorsque la sortie ressemble étroitement à l’entrée, ou lorsque vous devez appliquer la même transformation sur de nombreux champs sans répertorier chacun d’eux.

Copier tous les champs

Pour passer chaque champ sans modification :

Correspond * à chaque chemin de champ dans l’entrée et le place au même chemin dans la sortie. La partie du chemin d’accès qui * correspond est appelée segment capturé. Dans la sortie, le segment capturé remplace le *.

Champs imbriqués aplatis

Pour déplacer des champs hors d’un objet imbriqué au niveau racine, placez le préfixe dans l’entrée et * dans la sortie :

Étant donné cette entrée :

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

La sortie aplatit les deux objets :

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

Restructurer les champs

Pour déplacer des champs sous un nouveau parent, placez * l’entrée et ajoutez un préfixe dans la sortie :

Cela encapsule tous les champs de niveau supérieur à l’intérieur d’un Telemetry objet.

Règles de placement de caractères génériques

• * est autorisée par chemin d’entrée ou de sortie.
• Doit * correspondre à un segment complet (pas un segment partiel comme Sensor*).
• Il * peut apparaître au début (), au milieu (*.ValueSensors.*.Reading) ou à la fin (Sensors.*) d’un chemin d’accès.

Caractères génériques à entrées multiples

Lorsqu’une règle a plusieurs entrées avec des caractères génériques, elle * doit capturer le même segment sur toutes les entrées. Le runtime résout la * première entrée, puis recherche les chemins correspondants dans les autres entrées.

Par exemple, pour moyenner les lectures maximales et minimales pour chaque capteur :

Étant donné cette entrée :

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

Les * captures Temperature en premier, donc la règle recherche à la fois Temperature.Max et Temperature.Min. Ensuite, il capture Pressure et recherche Pressure.Max et Pressure.Min. La sortie est la suivante :

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

Si une entrée ne peut pas être résolue pour un segment capturé (par exemple, *.Mid.Avg lorsque le champ est imbriqué différemment), ce segment est ignoré. Assurez-vous que les chemins d’accès de toutes les entrées reflètent la structure réelle des données.

Remplacer un caractère générique pour des champs spécifiques

Vous pouvez combiner une règle générique avec des règles spécifiques. Les règles spécifiques sont prioritaires lorsqu’elles ont une couverture inférieure (moins de segments mis en correspondance par *). Il s’agit de la spécialisation.

La première règle s’applique à tous les champs. La deuxième règle la substitue uniquement, Pressure car Pressure.Max elle est plus spécifique que *.Max (couverture 0 et couverture 1).

Pour exclure entièrement un champ, utilisez une sortie vide :

Une sortie vide supprime le champ du résultat. Cela remplace toute règle générique qui l’inclurait autrement.

Plusieurs règles sur les mêmes entrées

Si deux règles ont une couverture identique ou supérieure, les deux s’appliquent. Cela vous permet de calculer plusieurs valeurs dérivées des mêmes entrées :

Les deux règles s’exécutent pour chaque segment capturé, produisant deux champs de sortie par capteur.

Caractères génériques dans les jeux de données de contextualisation

Vous pouvez utiliser des caractères génériques avec $context des références pour copier tous les champs d’un jeu de données :

Cette opération copie chaque champ du jeu de assetMeta données dans la Asset section de la sortie.

Jeux de données de contextualisation

Les jeux de données de contextualisation permettent aux mappages d’intégrer des données supplémentaires à partir de bases de données externes. Utilisez le $context(datasetName) préfixe pour référencer des champs à partir d’un jeu de données. Par exemple, $context(position).BaseSalary lit le BaseSalary champ à partir d’un jeu de données nommé position.

Pour plus d’informations sur la configuration des jeux de données de contextualisation, consultez Enrichir des données à l’aide de flux de données et Enrichir avec des données externes dans des graphiques de flux de données.

Contenu connexe

Si vous êtes arrivé ici à la recherche de la syntaxe utilisée dans une transformation spécifique, ces articles montrent des expressions dans leur contexte :

Pour les flux de données, voir Cartographier les données en utilisant les flux de données et Filtrer les données dans un flux de données.