syntax för Azure Time Series Insights Gen2-tidsserieuttryck

2023-08-05

Översikt

Time Series Expression (TSX) är ett strängbaserat uttrycksspråk med stark typning. TSX används för att representera följande entiteter i en Time Series-fråga.

Filtrera
Värde
Aggregering

Filteruttryck

Filteruttryck används för att representera booleska satser. I följande tabell visas exempel på filter:

TSX	Description
`$event.PointValue.Double = 3.14`	`true` för händelser med dubbla PointValue lika med `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true` för händelser med PointValue som är större än `3.14` och strängstatus `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` för händelser med en tidsstämpel som är större än `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` för händelser med PointValue lika med `true`

Värdeuttryck

Värdeuttryck används för att illustrera värdet för numeriska och kategoriska variabler. Ett värdeuttryck kan vara ett egenskapsreferensuttryck av typen Double eller Long.

Exempel:

TSX	Kommentarer
`$event.Temperature.Double`	Den sista token i ett värdeuttryck (i det här fallet `Double`) läss som egenskapens typ.
`$event.Temperature`	Typen antas vara Double för en egenskap som nås av en enda token.
`$event['Temperature-Celsius']`	Använd `[` och `]` för undantagstoken som har specialtecken. Använd dessutom `\` inom hakparenteserna för att undvika följande tecken: `\` och `'`.
`$event.Temperature.Celsius.Double`	Använd `.` för att komma åt kapslade egenskaper. Vid åtkomst till kapslade egenskaper krävs typen .
`$event.Temperature['Celsius-C'].Double`	Använd `[` och `]` för undantagstoken som har specialtecken vid åtkomst till kapslade egenskaper. Använd dessutom `\` inom hakparenteserna för att undvika följande tecken: `\` och `'`. Vid åtkomst till kapslade egenskaper krävs typen .
`$event['Temperature']['Celsius'].Double`	Användning av `[` och `]` för undantagstoken tillåts på valfri token.

Numerisk variabeltyp

Resultatet av värdeuttrycket ska vara av typen Double eller Long .

Mängdvariabeltyp

Resultatet av värdeuttrycket kan vara av valfri typ som stöds.

Kategorisk variabeltyp

Resultatet av värdeuttrycket får bara vara av typen String eller Long .

Sammansättningsuttryck

Mängduttryck används för att illustrera aggregeringsåtgärden som ska användas i frågan. Ett aggregeringsuttryck resulterar i ett enda värde för varje intervall. Mängduttryck kan tillämpas på numeriska variabler och aggregeringsvariabler.

Sammansättningsuttryck – numerisk variabeltyp

Numeriska variabler bör referera till $value.

Här är de mängdfunktioner som stöds.

Mängdfunktion	Exempel	Description
`min`	`min($value)`	Beräknar minimivärdet för `$value` per intervall. Undviker `null` värden. Kan inte användas med interpolering.
`max`	`max($value)`	Beräknar maxvärdet för `$value` per intervall. Undviker `null` värden. Kan inte användas med interpolering.
`sum`	`sum($value)`	Beräknar summan av `$value` för alla händelser i intervallet. Undviker `null` värden. Kan inte användas med interpolering.
`avg`	`avg($value)`	Beräknar medelvärdet av `$value` för alla händelser i intervallet. Undviker `null` värden. Kan inte användas med interpolering.
`first`	`first($value)`	Returnerar `$value` den första händelsen i intervallet efter händelsetidsstämpel. Undviker inte`null` värden. Kan inte användas med interpolering.
`last`	`last($value)`	Returnerar `$value` den senast inträffade händelsen i intervallet efter tidsstämpel för händelsen. Undviker inte`null` värden. Kan inte användas med interpolering.
`median`	`median($value)`	Returnerar `$value` den mellersta händelsen i intervallet efter tidsstämpel för händelsen. Undviker inte`null` värden. Kan inte användas med interpolering.
`stdev`	`stdev($value)`	Returnerar `$value` standardavvikelsen för händelserna i intervallet. Undviker `null` värden. Kan inte användas med interpolering.
`twsum`	`twsum($value)`	Returnerar `$value` den tidsviktade summan av händelserna i intervallet. Kräver interpolering.
`twavg`	`twavg($value)`	Returnerar `$value` det tidsviktade medelvärdet för händelserna i intervallet. Kräver interpolering.
`left`	`left($value)`	`$value` Returnerar vid vänsterkanten för det angivna intervallet. Kräver interpolering.
`right`	`right($value)`	`$value` Returnerar vid den högra kanten av det angivna intervallet. Kräver interpolering.

Sammansättningsuttryck – mängdvariabeltyp

Mängdvariabler ska referera till en egenskap i händelsenyttolasten.

Här är de mängdfunktioner som stöds.

Mängdfunktion	Exempel	Description
`count`	`count()`	Returnerar antalet händelser per intervall.
`min`	`min($event.Temperature.Double)`	Beräknar minimivärdet för egenskapen Temperatur per intervall. Undviker `null` värden.
`max`	`max($event.Temperature.Long)`	Beräknar maxvärdet för egenskapen Temperatur per intervall. Undviker `null` värden.
`sum`	`sum($event.Temperature.Double)`	Beräknar summan av egenskapen Temperature ( Temperatur ) för alla händelser i intervallet. Undviker `null` värden.
`avg`	`avg($event.Temperature.Long)`	Beräknar medelvärdet av egenskapen Temperature (Temperatur ) för alla händelser i intervallet. Undviker `null` värden.
`first`	`first($event.Temperature.String)`	Returnerar det första värdet (efter händelsetidsstämpel) för egenskapen Temperatur från alla händelser i intervallet. Undviker inte`null` värden.
`last`	`last($event.Temperature.String)`	Returnerar värdet för senast förekommande (efter händelsetidsstämpel) för egenskapen Temperatur från alla händelser i intervallet. Undviker inte`null` värden.
`median`	`median($event.Temperature.String)`	Returnerar värdet för mellanrummet (efter händelsetidsstämpel) för egenskapen Temperatur från alla händelser i intervallet. Undviker inte`null` värden.
`stdev`	`stdev($event.Temperature.String)`	Beräknar standardavvikelsen för egenskapen Temperatur per intervall. Undviker `null` värden.

För en mängdvariabeltyp kan dessa funktioner kombineras i mängduttrycket. Exempel: max($event.Temperature.Long) - min($event.Temperature.Long).

Syntax

I det här avsnittet beskrivs grundläggande syntaxbegrepp och frågeoperatorer som sammanfogas till formuläruttryck.

Literaler som stöds

Anteckning

Literalerna nedan används för att skapa uttryck. I artikeln Datatyper som stöds finns en fullständig lista över datatyper.

Primitiv typ	Literaler
Bool	`TRUE`, `FALSE`
DateTime	`dt'2016-10-08T03:22:55.3031599Z'`
Dubbel	`1.23`, `1.0`
Lång	`1`, `6`
Sträng	`'abc'`
Gått	`ts'P1Y2M3DT4M5.67S'`
Null	`NULL`

Operandtyper som stöds

Åtgärd	Typer som stöds	Kommentarer
<, >, <=, >=	Double, Long, DateTime, TimeSpan
=, !=, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> motsvarar !=
+, -, *, /	Double, Long, DateTime, TimeSpan

För jämförelseuttryck (<, >, <=, >=, =, !=) kan operanderna vara NULL eller ha samma typ. I varje predikatuttryck valideras typer av LHS-operander (vänster sida) och rhs-operander (höger sida) för att matcha. Fel uppstår när typer av LHS och RHS inte accepterar, eller om en åtgärd inte tillåts för vissa typer.

Anteckning

Strängtypen kan inte ha värdet null i det varma arkivet:

Jämförelse av Sträng mot NULL och tom sträng ('') fungerar på samma sätt: $event.p1.String = NULL motsvarar $event.p1.String = ''.
API kan returnera NULL-värden även om ursprungliga händelser innehåller tomma strängar.

I framtiden kommer samma beteende att finnas på Cold Store.

Var inte beroende av NULL-värden i strängkolumner och behandla dem på samma sätt som tomma strängar.

En typkontroll tillämpas:
- Alla egenskapstyper accepteras mot en NULL literal.
- Typer av LHS och RHS bör matcha.

Här följer exempel på egenskaperna p1 och p2 av typen String, egenskapen p3 av typen Double och en kapslad egenskap som lagras som p4.p5 av typen Double:

Filtrera	Är giltig?	Kommentarer
`$event.p1.String = 'abc'`	Ja
`$event.p1.String = $event.p2.String`	Ja
`$event.p1.String = NULL`	Yes	`NULL` matchar valfri typ av vänster sida.
`$event.p3.Double = 'abc'`	No	Typmatchningsfel.
`$event.p3.Double = $event.p1.String`	No	Typmatchningsfel.
`$event.p1 = 'abc'`	No	Typmatchningsfel.
`$event.p1 = 1`	No	Typmatchningsfel.
`$event.p1 = true`	No	Typmatchningsfel.
`$event.p1 = NULL`	Yes	`p1` är den enda token som används. Tolkas som `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Yes	`['p1']` är den enda token som används. Tolkas som `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	No	Ogiltig egenskapsreferenssyntax. En typ måste anges på LHS för jämförelse.
`$event.p4.p5.Double = 0.0`	Yes

Skalära funktioner som stöds

Nedan visas listan över skalärfunktioner efter kategorier:

Konverteringsfunktioner

Funktionsnamn	Signatur	Exempel	Anteckningar
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Konverterar argumenten till Double.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Konverterar argumenten till Long.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Konverterar argument till Sträng.

Matematiska funktioner

Funktionsnamn	Signatur	Exempel	Anteckningar
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Avrundar ett flytande tal med dubbel precision till närmaste integral.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Returnerar det minsta integralvärdet som är större än eller lika med flyttal med dubbel precision.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Returnerar det största integralvärdet som är mindre än eller lika med flyttal med dubbel precision.

Trigonometriska funktioner

Funktionsnamn	Signatur	Exempel	Anteckningar
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Returnerar Cosinin för den angivna vinkeln i radianer.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Returnerar sinus för den angivna vinkeln i radianer.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Returnerar tangens för den angivna vinkeln i radianer.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Returnerar vinkeln i radianer vars Cosiné är det angivna talet.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Returnerar vinkeln i radianer vars sinus är det angivna talet.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Returnerar vinkeln i radianer vars Tang är det angivna talet.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Returnerar vinkeln i radianer vars Tangent är kvoten för två angivna tal.

Logaritmiska funktioner

Funktionsnamn	Signatur	Exempel	Anteckningar
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Returnerar den naturliga logaritmen för ett angivet tal.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Returnerar bas 2-logaritmen för ett angivet tal.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Returnerar bas 10 logaritmen för ett angivet tal.

DateTime Functions

Funktionsnamn	Signatur	Exempel	Anteckningar
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Returnerar månaden på året som ett numeriskt värde för den angivna DateTime.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Returnerar dagen i månaden som ett numeriskt värde för den angivna DateTime.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Returnerar timmen på dagen som ett numeriskt värde för den angivna DateTime.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Returnerar aktuell tid i UTC-format.

Strängfunktioner

Funktionsnamn	Signatur	Exempel	Anteckningar
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Returnerar indatasträng som konverterats till versaler.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Returnerar indatasträng som konverterats till gemener.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Returnerar antalet tecken i strängargumentet.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Sammanfogar två angivna indatasträngar.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Hämtar en delsträng från den här instansen.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Returnerar en ny sträng genom att ta bort alla inledande och avslutande blankstegstecken från indatasträngen.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Returnerar den första förekomsten av den angivna strängen i den ursprungliga strängen, baserat på nollindexering.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Returnerar en sträng där alla förekomster av söksträngen ersätts med ersättningssträngen.

Andra funktioner

Funktionsnamn	Signatur	Exempel	Anteckningar
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Returnerar det första värdet som inte är null i argumentlistan. Accepterar minst 2 och högst 64 argument, men alla måste ha samma datatyp.
`iff`	`String, Long, Double, Bool iff (predicate: bool, ifTrue: String, Long, Double, Bool, ifFalse: String, Long, Double, Bool)`	`iff ($event.value.Double > 100, 'Good', 'Bad')`	Returnerar det andra eller tredje argumentet beroende på om predikatet har matchats till sant (returnerar andra argumentet) eller falskt (returnerar tredje argumentet). Predikatet måste vara ett booleskt uttryck och det andra och tredje argumentet måste ha samma typ.

Se även

Mer information om programregistrering och Azure Active Directory-programmeringsmodellen finns i Azure Active Directory för utvecklare.
Mer information om parametrar för begäran och autentisering finns i Autentisering och auktorisering.
Verktyg som hjälper dig att testa HTTP-begäranden och svar är:
Fiddler. Den här kostnadsfria webbfelsökningsproxyn kan fånga upp dina REST-begäranden så att du kan diagnostisera HTTP-begäran och svarsmeddelanden.
JWT.io. Du kan använda det här verktyget för att snabbt dumpa anspråken i ägartoken och sedan verifiera innehållet.
Postman. Det här är ett kostnadsfritt testverktyg för HTTP-begäran och svar för felsökning av REST-API:er.
Läs mer om Azure Time Series Insights Gen2 genom att läsa Gen2-dokumentationen.

Dela via