Syntaxe výrazu časové řady Azure Time Series Insights Gen2

Článek
08/05/2023

Přehled

Time Series Expression (TSX) je jazyk výrazů založený na řetězcích se silným psaním. TSX se používá k reprezentaci následujících entit v dotazu časové řady.

Filtrovat
Hodnota
Agregace

Výrazy filtru

Výrazy filtru se používají k reprezentaci logických klauzulí. Následující tabulka uvádí příklady filtrů:

TSX	Description
`$event.PointValue.Double = 3.14`	`true` pro události s dvojitou hodnotou PointValue rovnou `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true` pro události s hodnotou PointValue větší než `3.14` a stavem řetězce `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` pro události s časovým razítkem větším než `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` pro události, které mají hodnotu PointValue rovnou `true`

Výrazy hodnot

Výrazy hodnot se používají k znázornění hodnoty číselných proměnných a proměnných kategorií. Výrazem hodnoty může být výraz odkazu na vlastnost typu Double nebo Long.

Příklad:

TSX	Poznámky
`$event.Temperature.Double`	Poslední token v libovolné hodnotě výrazu (v tomto případě `Double`) se přečte jako Typ vlastnosti .
`$event.Temperature`	U vlastnosti, ke které přistupuje jeden token, se předpokládá typ Double .
`$event['Temperature-Celsius']`	K uvozování tokenů se speciálními znaky použijte `[` a `]` . Kromě toho použijte `\` v hranatých závorkách následující znaky: `\` a `'`.
`$event.Temperature.Celsius.Double`	Slouží `.` k přístupu k vnořeným vlastnostem. Při přístupu k vnořeným vlastnostem se vyžaduje Typ.
`$event.Temperature['Celsius-C'].Double`	K uvozování tokenů, které mají speciální znaky při přístupu k vnořeným vlastnostem, použijte `[` a `]` . Kromě toho použijte `\` v hranatých závorkách následující znaky: `\` a `'`. Při přístupu k vnořeným vlastnostem se vyžaduje Typ.
`$event['Temperature']['Celsius'].Double`	`[` Použití a `]` pro uvozování tokenů je povoleno u jakéhokoli tokenu.

Druh číselné proměnné

Výsledek výrazu hodnoty by měl být typu Double nebo Long .

Druh agregační proměnné

Výsledek výrazu hodnoty může být libovolného podporovaného typu.

Druh proměnné v kategoriích

Výsledek výrazu hodnoty může být pouze typ String nebo Long .

Výrazy pro agregaci

Agregační výrazy slouží k znázornění agregační operace, která se má v dotazu použít. Výsledkem agregačního výrazu je jedna hodnota pro každý interval. Agregační výrazy lze použít u číselných a agregačních proměnných.

Agregační výrazy – druh číselné proměnné

Číselné proměnné by měly odkazovat na $value.

Tady jsou podporované agregační funkce.

Agregační funkce	Příklad	Description
`min`	`min($value)`	Vypočítá minimum intervalu `$value` . Vyhýbá se hodnotám `null` . Nelze použít s interpolací.
`max`	`max($value)`	Vypočítá maximální počet intervalů `$value` . Vyhýbá se hodnotám `null` . Nelze použít s interpolací.
`sum`	`sum($value)`	Vypočítá součet `$value` všech událostí v intervalu. Vyhýbá se hodnotám `null` . Nelze použít s interpolací.
`avg`	`avg($value)`	Vypočítá průměr `$value` všech událostí v intervalu. Vyhýbá se hodnotám `null` . Nelze použít s interpolací.
`first`	`first($value)`	Vrátí `$value` první výskyt události v intervalu podle časového razítka události. Nevyhýbá se `null` hodnotám. Nelze použít s interpolací.
`last`	`last($value)`	Vrátí poslední `$value` výskyt události v intervalu podle časového razítka události. Nevyhýbá se `null` hodnotám. Nelze použít s interpolací.
`median`	`median($value)`	Vrátí `$value` prostřední událost v intervalu podle časového razítka události. Nevyhýbá se `null` hodnotám. Nelze použít s interpolací.
`stdev`	`stdev($value)`	Vrátí `$value` směrodatnou odchylku událostí v intervalu. Vyhýbá se hodnotám `null` . Nelze použít s interpolací.
`twsum`	`twsum($value)`	Vrátí `$value` časově vážený součet událostí v intervalu. Vyžaduje interpolaci.
`twavg`	`twavg($value)`	Vrátí `$value` časově vážený průměr událostí v intervalu. Vyžaduje interpolaci.
`left`	`left($value)`	Vrátí hodnotu `$value` na levém okraji daného intervalu. Vyžaduje interpolaci.
`right`	`right($value)`	Vrátí hodnotu `$value` na pravém okraji daného intervalu. Vyžaduje interpolaci.

Agregační výrazy – druh agregační proměnné

Agregované proměnné by měly odkazovat na vlastnost v datové části události.

Tady jsou podporované agregační funkce.

Agregační funkce	Příklad	Description
`count`	`count()`	Vrátí počet událostí v intervalu.
`min`	`min($event.Temperature.Double)`	Vypočítá minimum vlastnosti Temperature za interval. Vyhýbá se hodnotám `null` .
`max`	`max($event.Temperature.Long)`	Vypočítá maximální hodnotu vlastnosti Temperature na interval. Vyhýbá se hodnotám `null` .
`sum`	`sum($event.Temperature.Double)`	Vypočítá součet vlastnosti Temperature (Teplota ) pro všechny události v intervalu. Vyhýbá se hodnotám `null` .
`avg`	`avg($event.Temperature.Long)`	Vypočítá průměr vlastnosti Temperature za všechny události v intervalu. Vyhýbá se hodnotám `null` .
`first`	`first($event.Temperature.String)`	Vrátí první výskyt (podle časového razítka události) hodnotu vlastnosti Temperature ze všech událostí v intervalu. Nevyhýbá se `null` hodnotám.
`last`	`last($event.Temperature.String)`	Vrátí hodnotu posledního výskytu (podle časového razítka události) vlastnosti Temperature ze všech událostí v intervalu. Nevyhýbá se `null` hodnotám.
`median`	`median($event.Temperature.String)`	Vrátí hodnotu prostředního výskytu (podle časového razítka události) vlastnosti Temperature ze všech událostí v intervalu. Nevyhýbá se `null` hodnotám.
`stdev`	`stdev($event.Temperature.String)`	Vypočítá směrodatnou odchylku vlastnosti Temperature podle intervalu. Vyhýbá se hodnotám `null` .

U typu agregační proměnné je možné tyto funkce kombinovat v agregačním výrazu. Příklad: max($event.Temperature.Long) - min($event.Temperature.Long).

Syntax

Tato část popisuje základní koncepty syntaxe a operátory dotazů, které jsou zřetězeny do výrazů formulářů.

Podporované literály

Poznámka

Následující literály se používají k formování výrazů. Úplný seznam datových typů najdete v článku Podporované datové typy .

Primitivní typ	Literály
Bool	`TRUE`, `FALSE`
Datum a čas	`dt'2016-10-08T03:22:55.3031599Z'`
dvojité	`1.23`, `1.0`
Dlouhé	`1`, `6`
Řetězec	`'abc'`
TimeSpan	`ts'P1Y2M3DT4M5.67S'`
Null	`NULL`

Podporované typy operandů

Operace	Podporované typy	Poznámky
<, >, <=, >=	Double, Long, DateTime, TimeSpan
=, !=, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> je ekvivalentem !=
+, -, *, /	Double, Long, DateTime, TimeSpan

U porovnávacích výrazů (<, >, =<, >=, =!=) můžou být operandy null nebo stejného typu. V každém výrazu predikátu se ověří shoda typů operandů na levé straně (LHS) a pravé strany (RHS). K chybám dochází v případě, že se typy LHS a RHS neshodují nebo u konkrétních typů není povolená operace.

Poznámka

Typ řetězce v teplém úložišti nemůže být null:

Porovnání řetězce s hodnotou NULL a prázdný řetězec ('') se chová stejně: $event.p1.String = NULL je ekvivalentní hodnotě $event.p1.String = ''.
Rozhraní API může vracet hodnoty NULL i v případě, že původní události obsahovaly prázdné řetězce.

V budoucnu se stejné chování bude chovat i v úložišti cold store.

Nespolézejte se na hodnoty NULL ve sloupcích řetězců a zacházejte s nimi stejně jako s prázdnými řetězci.

Použije se kontrola typu:
- Proti literálu NULL se akceptuje libovolný typ vlastnosti.
- Typy LHS a RHS by se měly shodovat.

Tady jsou příklady vlastností p1 a p2 typu String, vlastnost p3 typu Double a vnořená vlastnost uložená jako p4.p5 typu Double:

Filtrovat	Je platný?	Poznámky
`$event.p1.String = 'abc'`	Yes
`$event.p1.String = $event.p2.String`	Ano
`$event.p1.String = NULL`	Ano	`NULL` odpovídá libovolnému typu na levé straně.
`$event.p3.Double = 'abc'`	No	Neshoda typů
`$event.p3.Double = $event.p1.String`	Ne	Neshoda typů
`$event.p1 = 'abc'`	Ne	Neshoda typů
`$event.p1 = 1`	Ne	Neshoda typů
`$event.p1 = true`	Ne	Neshoda typů
`$event.p1 = NULL`	Yes	`p1` je jediný použitý token. Interpretováno jako `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Yes	`['p1']` je jediný použitý token. Interpretováno jako `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	No	Neplatná syntaxe odkazu na vlastnost Typ musí být zadán v LHS porovnání.
`$event.p4.p5.Double = 0.0`	Yes

Podporované skalární funkce

Níže je seznam skalárních funkcí podle kategorií:

Převodní funkce

Název funkce	Podpis	Příklad	Poznámky
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Převede argumenty na double.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Převede argumenty na long.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Převede argumenty na řetězec.

Matematické funkce

Název funkce	Podpis	Příklad	Poznámky
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Zaokrouhlí číslo s plovoucí dvěma přesnostmi na nejbližší integrál.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Vrátí nejmenší celočíselnou hodnotu, která je větší než nebo rovna číslu s plovoucí desetinou čárkou s dvojitou přesností.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Vrátí největší celočíselnou hodnotu, která je menší než nebo rovna číslu s plovoucí desetinou čárkou s dvojitou přesností.

Trigonometrické funkce

Název funkce	Podpis	Příklad	Poznámky
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Vrátí kosinus zadaného úhlu v radiánech.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Vrátí sinus zadaného úhlu v radiánech.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Vrátí tangens zadaného úhlu v radiánech.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Vrátí úhel v radiánech, jejichž kosinus je zadané číslo.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Vrátí úhel v radiánech, jejichž sinus je zadané číslo.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Vrátí úhel v radiánech, jejichž tangens je zadané číslo.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Vrátí úhel v radiánech, jejichž tangens je podílem dvou zadaných čísel.

Logaritmické funkce

Název funkce	Podpis	Příklad	Poznámky
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Vrátí přirozený logaritmus zadaného čísla.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Vrátí logaritmus 2. základu zadaného čísla.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Vrátí dekadický logaritmus zadaného čísla.

Funkce data a času

Název funkce	Podpis	Příklad	Poznámky
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Vrátí měsíc v roce jako číselnou hodnotu pro zadané datum a čas.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Vrátí den v měsíci jako číselnou hodnotu pro zadané datum a čas.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Vrátí hodinu dne jako číselnou hodnotu pro zadané datum a čas.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Vrátí aktuální čas ve formátu UTC.

Funkce řetězců

Název funkce	Podpis	Příklad	Poznámky
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Vrátí vstupní řetězec převedený na velká písmena.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Vrátí vstupní řetězec převedený na malá písmena.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Vrátí počet znaků v řetězcovém argumentu.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Zřetězí dva zadané vstupní řetězce.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Načte podřetězec z této instance.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Vrátí nový řetězec odebráním všech počátečních a koncových prázdných znaků ze vstupního řetězce.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Vrátí první výskyt zadaného řetězce v původním řetězci na základě nulového indexování.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Vrátí řetězec, ve kterém jsou všechny výskyty hledaného řetězce nahrazeny náhradním řetězcem.

Další funkce

Název funkce	Podpis	Příklad	Poznámky
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Vrátí první hodnotu v seznamu argumentů, která není null. Přijímá minimálně 2 a maximálně 64 argumentů, ale všechny musí mít stejný datový typ.
`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')`	Vrátí druhý nebo třetí argument v závislosti na tom, jestli se predikát přeložil na true (vrátí druhý argument) nebo nepravda (vrátí třetí argument). Predikát musí být logický výraz a druhý a třetí argument musí být stejného typu.

Viz také

Další informace o registraci aplikací a programovacím modelu Azure Active Directory najdete v tématu Azure Active Directory pro vývojáře.
Další informace o parametrech požadavků a ověřování najdete v tématu Ověřování a autorizace.
Mezi nástroje, které pomáhají s testováním požadavků a odpovědí HTTP, patří:
Fiddler. Tento bezplatný proxy server pro ladění webu může zachycovat vaše požadavky REST, abyste mohli diagnostikovat zprávy požadavků a odpovědí HTTP.
JWT.io. Tento nástroj můžete použít k rychlému výpisu deklarací identity v nosném tokenu a následnému ověření jejich obsahu.
Postman. Toto je bezplatný nástroj pro testování požadavků a odpovědí HTTP pro ladění rozhraní REST API.
Další informace o Azure Time Series Insights Gen2 najdete v dokumentaci k Gen2.