Riferimento alle espressioni per flussi di dati e grafici di flusso di dati

Questo riferimento si applica sia ai flussi di dati che ai grafici del flusso di dati. Entrambi usano lo stesso linguaggio delle espressioni per le trasformazioni di mapping, filtro e arricchimento. I grafici del flusso di dati supportano anche trasformazioni di rami e finestre (accumulo), indicate se applicabile.

Variabili posizionale

La matrice di inputs ogni regola determina le variabili disponibili in expression. Il primo input diventa $1, il secondo diventa $2e così via.

Se viene specificato un solo input e non viene specificata alcuna espressione, il valore in corrispondenza dell'input viene copiato direttamente nell'output.

Operatori

Le espressioni supportano gli operatori seguenti, elencati dalla precedenza più alta alla più bassa:

L'operatore + concatena le stringhe quando almeno un operando è una stringa. Usare le parentesi per eseguire l'override della precedenza predefinita.

Esempi:

Funzioni predefinite

Funzioni di conversione unità

Queste funzioni accettano un singolo valore numerico e restituiscono un valore float.

Funzioni di ridimensionamento e arrotondamento

Funzioni matematiche

Queste funzioni provengono dalla libreria matematica predefinita.

Funzioni stringa

Funzioni di data e ora

Le funzioni data e ora sono disponibili solo nei grafici di flusso dei dati. Ad eccezione di parse_timestamp, le funzioni che accettano un timestamp richiedono una stringa RFC 3339 . La stringa deve includere uno spostamento esplicito rispetto al Tempo Universale Coordinato (UTC), come 2026-06-17T12:00:00Z o 2026-06-17T12:00:00-08:00. La Returns colonna elenca il tipo di risultato concettuale, che typeof riporta in minuscola come "float", "int", o "string".

now() legge l'orologio di sistema del nodo Kubernetes che ospita il carico di lavoro del flusso dati ogni volta che la funzione viene eseguita. Le chiamate nella stessa espressione possono restituire valori diversi. In una regola di accumulo, now() restituisce il momento in cui la finestra viene elaborata, non quando arriva un messaggio di input. Per ridurre lo sfasamento di clock tra i nodi del cluster, sincronizza ogni clock di ogni nodo con una sorgente di tempo affidabile, come un server Network Time Protocol.

Le funzioni di calendario e orologio, come day_of_week, hour_of_day, e year_of, utilizzano lo offset nel timestamp di input. Non convertono prima il valore in UTC. Gli esempi seguenti mostrano questo comportamento.

Formato e timestamp di analisi

Le format_timestamp funzioni e parse_timestamp usano strftime schemi. La tabella seguente elenca gli specificatori comuni.

Per tutti gli specificatori supportati, consulta la documentazione Chrono strftime.

format_timestamp conserva lo offset temporale dell'ingresso. Ad esempio format_timestamp("2026-06-09T14:00:00+02:00", "%Y-%m-%d %H:%M %:z") restituisce "2026-06-09 14:00 +02:00".

parse_timestamp gestisce gli input nel seguente ordine:

1. Una data e un orario con un offset numerico. La funzione rispetta lo offset e normalizza il risultato su UTC.
2. Una data e un orario senza spostamento. La funzione presuppone UTC.
3. Un appuntamento senza orario. La funzione presume mezzanotte UTC.

I seguenti esempi mostrano come parse_timestamp gestisce ogni tipo di input.

Converti i valori dell'epoca Unix

Usare from_epoch e to_epoch per convertire tra valori epoche Unix e timestamp RFC 3339.

from_epoch accetta valori negativi per le date precedenti al 1° gennaio 1970. Il suo output ha precisione millisecondaria, quindi convertire microsecondi epoche in un timestamp scarta la precisione inferiore a un millisecondo. to_epoch tiene conto dello spostamento UTC del timestamp e arrotonda i valori precedenti al 1970 fino all'intero inferiore successivo per l'unità selezionata.

Possono essere composte funzioni di data e ora. Ad esempio, duration_between($1, now(), "days") calcola l'età in giorni di un timestamp RFC 3339 fornito come primo input di regola. Per leggere l'ora di un timestamp dopo averlo convertito in UTC, usa hour_of_day(from_epoch(to_epoch($1, "micros"), "micros")).

Funzioni condizionali e di raccolta

Funzioni di aggregazione (solo trasformazioni di finestra)

Queste funzioni sono disponibili solo nelle regole di accumulo all'interno delle trasformazioni di finestra. Ognuno accetta una singola variabile posizionale.

Per informazioni dettagliate sull'uso delle funzioni di aggregazione, vedere Aggregare i dati nel tempo.

Logica condizionale

Usare la funzione per diramare la if logica all'interno di un'espressione:

Usare () (il valore vuoto) nei confronti per rilevare i campi mancanti.

Campi dei metadati

Leggere e scrivere nei metadati dei messaggi usando il $metadata. prefisso nei inputs campi o output di una regola. I riferimenti ai metadati vengono inseriti nel percorso del campo, non nell'espressione stessa.

Proprietà dei metadati

• Argomento: funziona sia per MQTT che per Kafka. Contiene la stringa in cui è stato pubblicato il messaggio. Esempio: $metadata.topic.
• Proprietà utente: in MQTT, si riferisce alle coppie chiave/valore in formato libero che un messaggio MQTT può contenere. Ad esempio, se il messaggio MQTT è stato pubblicato con una proprietà utente con la chiave "priority" e il valore "high", il $metadata.user_property.priority riferimento contiene il valore "high". Le chiavi delle proprietà utente possono essere stringhe arbitrarie e possono richiedere l'uso di caratteri di escape: $metadata.user_property."weird key" utilizza la chiave "chiave strana" (che contiene uno spazio).
• Proprietà di sistema: questo termine viene usato per ogni proprietà che non è una proprietà utente. Attualmente è supportata solo una singola proprietà di sistema: $metadata.system_property.content_type, che legge la proprietà del tipo di contenuto del messaggio MQTT (se impostata).
• Intestazione: Questa è l'equivalente Kafka della proprietà utente MQTT. Kafka può usare qualsiasi valore binario per una chiave, ma i flussi di dati supportano solo chiavi stringa UTF-8. Esempio: $metadata.header.priority. Questa funzionalità è simile alle proprietà utente.

Leggere dai metadati

Per fare riferimento all'argomento di origine e a una proprietà utente in un'espressione, elencarli come input:

Espressione: $1 + "/" + $2

Nell'esempio seguente, la proprietà MQTT topic è mappata nel campo origin_topic nell'output.

Se la proprietà priority utente è presente nel messaggio MQTT, l'esempio seguente illustra come eseguirne il mapping a un campo di output:

Scrivere nei metadati

Per impostare una proprietà utente nel messaggio di output, usare $metadata.user_property.<key> come campo di output.

L'impostazione di un campo di metadati su un valore vuoto (()) lo rimuove. Per le proprietà utente, sono consentite chiavi duplicate.

È anche possibile eseguire il mapping delle proprietà dei metadati a un'intestazione di output o a una proprietà utente. Nell'esempio seguente, il MQTT topic è mappato al campo origin_topic nella proprietà utente dell'output.

Se il payload in ingresso contiene un priority campo, l'esempio seguente illustra come eseguirne il mapping a una proprietà utente MQTT:

Lo stesso esempio per Kafka:

I campi dei metadati sono supportati nelle regole di mapping, filtro e ramo. Non sono disponibili nelle regole di finestra (accumulo).

Ultimo valore noto

Usare il ? $last suffisso su un input per indicare al runtime di ricordare il valore più recente per tale campo. Se il campo non è presente nel messaggio corrente, viene invece utilizzato l'ultimo valore noto.

La ? $last direttiva non fa distinzione tra maiuscole e minuscole e supporta spazi vuoti flessibili.

L'ultimo valore noto è supportato nelle regole di mapping, filtro e ramo. Non è disponibile nelle regole di finestra (accumulo).

Valori predefiniti

Usare il ?? <default> suffisso su un input per fornire un valore di fallback quando il campo non è presente. Tipi predefiniti supportati: integer, float, boolean, string e null.

Combinare l'ultimo valore noto e il valore predefinito

È possibile combinare ? $last e ?? <default>. Il runtime controlla prima il messaggio corrente, quindi l'ultimo valore noto, quindi il valore predefinito. Se si usa ?? <default> senza ? $last, il runtime controlla direttamente il messaggio corrente e quindi il valore predefinito.

I valori predefiniti sono supportati nelle regole di mapping, filtro e ramo. Non sono disponibili nelle regole di finestra (accumulo).

Tipi di dati

Gli oggetti JSON e le matrici vengono mantenuti as-is quando i campi vengono copiati senza un'espressione, ma non possono essere usati come input per la valutazione delle espressioni.

Supporto delle funzionalità per tipo di trasformazione

Lo stesso linguaggio delle espressioni funziona tra trasformazioni, ma il risultato di un'espressione significa qualcosa di diverso in ciascuna:

¹ Disponibile solo nei grafici del flusso di dati. Non supportato negli input del flusso builtInTransformation di dati.

Notazione e escape dei punti

La notazione punto viene ampiamente usata per fare riferimento a campi annidati. Un percorso di notazione punto standard è simile a Person.Address.Street.Number.

In un flusso di dati, un percorso descritto dalla notazione punto può includere stringhe e alcuni caratteri speciali senza dover eseguire l'escape, ad esempio Person.Date of Birth.

In altri casi, l'escape è necessario, ad esempio: nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Questo percorso, tra gli altri caratteri speciali, contiene punti all'interno del nome del campo. Senza escape, il nome del campo fungerebbe da separatore nella notazione del punto stesso.

Mentre un flusso di dati analizza un percorso, tratta solo due caratteri come speciali:

• I punti (.) fungono da separatori di campo.
• Le doppie virgolette, quando poste all'inizio o alla fine di un segmento, iniziano una sezione sfuggita dove i punti non sono trattati come separatori di campo.

Tutti gli altri caratteri vengono considerati come parte del nome del campo. Questa flessibilità è utile in formati come JSON, in cui i nomi dei campi possono essere stringhe arbitrarie.

La definizione del percorso deve inoltre rispettare le regole del formato di configurazione. Quando un carattere con un significato speciale viene incluso nel percorso, è necessario inserire le virgolette appropriate. Ad esempio, i nomi di campo che iniziano con due punti (ad :Person:.:name:esempio ) o che iniziano con un numero seguito da testo (ad 100 celsius.hotesempio ) devono essere interpretati correttamente come stringhe.

Evasione

La funzione primaria di escape in un percorso con notazione punto consiste nell'usare punti che fanno parte dei nomi dei campi anziché dei separatori. Ad esempio, il percorso Payload."Tag.10".Value è costituito da tre segmenti: Payload, Tag.10e Value. Le virgolette doppie impediscono Tag.10 al punto di fungere da separatore.

Regole di escape nella notazione con punti

• Esegui l'escape di ciascun segmento separatamente: nel caso in cui più segmenti contengano punti, tali segmenti devono essere racchiusi tra virgolette doppie. Anche altri segmenti possono essere racchiusi tra virgolette, ma non influisce sull'interpretazione del percorso. Ad esempio: Payload."Tag.10".Measurements."Vibration.$12".Value

• Cita un segmento solo quando deve essere liberato. Aggiungi virgolette doppie intorno a un segmento solo quando contiene un punto (o un altro carattere che altrimenti verrebbe interpretato erroneamente come separatore). Non citare un nome di campo qualunque.

  Ad esempio, per un campo chiamato TagName all'interno Recordsdi :

  Fai questo	Non questo
  Records.TagName	Records."TagName"

  Le virgolette extra non aiutano e, in alcuni strumenti, come l'editor di flusso dati dell'esperienza operativa, diventano parte del nome del campo. La mappatura poi cerca un campo chiamato "TagName" (virgolette incluse), che non esiste, quindi nulla corrisponde. Puoi individuarlo nella definizione del flusso dati esportato, dove il nome appare con virgolette sfuggite, come \"TagName\". Per risolverlo, rimuovi le virgolette in modo che il nome sia semplicemente TagName.

• Uso corretto delle virgolette doppie: le virgolette doppie devono aprire e chiudere un segmento di testo tra virgolette. Tutte le virgolette al centro del segmento vengono considerate parte del nome del campo. Ad esempio, il percorso Payload.He said: "Hello", and waved definisce due campi: Payload e He said: "Hello", and waved. Quando un punto viene visualizzato in queste circostanze, continua a fungere da separatore. Ad esempio, il percorso Payload.He said: "No. It is done" viene suddiviso nei segmenti Payload, He said: "Noe It is done" (a partire da uno spazio).

Algoritmo di segmentazione

• Se il primo carattere di un segmento è una virgoletta, il parser cerca la virgoletta successiva. La stringa racchiusa tra queste virgolette è considerata un singolo segmento.
• Se il segmento non inizia con virgolette, il parser identifica i segmenti cercando il punto successivo o la fine del percorso.

Caratteri jolly

Usare un carattere jolly (*) nei percorsi di input e output per trovare una corrispondenza con più campi contemporaneamente. Ciò è utile quando l'output è simile all'input o quando è necessario applicare la stessa trasformazione in molti campi senza elencarne uno.

Copiare tutti i campi

Per passare ogni campo senza modifiche:

Corrisponde * a ogni percorso di campo nell'input e lo inserisce nello stesso percorso nell'output. La parte del percorso corrispondente * viene chiamata segmento acquisito. Nell'output il segmento acquisito sostituisce .*

Appiattire i campi annidati

Per spostare i campi da un oggetto annidato al livello radice, inserire il prefisso nell'input e * nell'output:

Dato questo input:

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

L'output rende flat entrambi gli oggetti:

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

Ristrutturare i campi

Per spostare i campi in un nuovo elemento padre, inserire * l'input e aggiungere un prefisso nell'output:

In questo modo vengono inclusi tutti i campi di primo livello all'interno di un Telemetry oggetto .

Regole di posizionamento con caratteri jolly

• È consentito un solo valore* per input o percorso di output.
• Deve * corrispondere a un segmento completo (non a un segmento parziale come Sensor*).
• Può * essere visualizzato all'inizio (*.Value), al centro (Sensors.*.Reading) o alla fine (Sensors.*) di un percorso.

Caratteri jolly a più input

Quando una regola ha più input con caratteri jolly, deve * acquisire lo stesso segmento in tutti gli input. Il runtime risolve l'oggetto * dal primo input, quindi cerca i percorsi corrispondenti negli altri input.

Ad esempio, per mediare le letture massime e minime per ogni sensore:

Dato questo input:

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

L'oggetto * acquisisce Temperature prima di tutto, quindi la regola cerca sia Temperature.Max che Temperature.Min. Acquisisce Pressure quindi e cerca Pressure.Max e Pressure.Min. L'output è il seguente:

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

Se un input non può essere risolto per un segmento acquisito(ad esempio, *.Mid.Avg quando il campo è annidato in modo diverso), tale segmento viene ignorato. Assicurarsi che i percorsi in tutti gli input riflettano la struttura effettiva dei dati.

Eseguire l'override di un carattere jolly per campi specifici

È possibile combinare una regola con caratteri jolly con regole specifiche. Le regole specifiche hanno la precedenza quando hanno una copertura inferiore (meno segmenti corrispondono a *). Questa operazione è denominata specializzazione.

La prima regola si applica a tutti i campi. La seconda regola esegue l'override solo per Pressure , perché Pressure.Max è più specifica di *.Max (copertura 0 e copertura 1).

Per escludere completamente un campo, usare un output vuoto:

Un output vuoto elimina il campo dal risultato. In questo modo viene eseguito l'override di qualsiasi regola con caratteri jolly che altrimenti lo includerebbe.

Più regole sugli stessi input

Se due regole hanno la stessa copertura o superiore, entrambe si applicano. In questo modo è possibile calcolare più valori derivati dagli stessi input:

Entrambe le regole vengono eseguite per ogni segmento acquisito, producendo due campi di output per sensore.

Caratteri jolly nei set di dati di contestualizzazione

È possibile usare caratteri jolly con $context riferimenti per copiare tutti i campi da un set di dati:

In questo modo ogni campo del assetMeta set di dati viene copiato nella Asset sezione dell'output.

Set di dati di contestualizzazione

I set di dati di contestualizzazione consentono ai mapping di integrare dati aggiuntivi da database esterni. Usare il $context(datasetName) prefisso per fare riferimento ai campi di un set di dati. Ad esempio, $context(position).BaseSalary legge il BaseSalary campo da un set di dati denominato position.

Per informazioni dettagliate sulla configurazione dei set di dati di contestualizzazione, vedere Arricchire i dati usando i flussi di dati e Arricchire i dati esterni nei grafici del flusso di dati.

Contenuti correlati

Se sei arrivato qui cercando la sintassi usata in una trasformata specifica, questi articoli mostrano espressioni nel contesto:

Per i flussi di dati, vedi Mappare i dati usando flussi di dati e Filtrare i dati in un flusso di dati.