syntaxe dotazu Azure Time Series Insights Gen1

Článek
08/05/2023

Upozornění

Toto je článek Gen1.

Tento článek popisuje formát a syntaxi požadavku dotazu rozhraní API Azure Time Series Insights Gen1.

Souhrn

Důležité

Požadavky dotazů musí být ve formátu JSON.
Datové části požadavků HTTP vytvořené v rozhraní API pro dotazy by měly odpovídat formátu zadanému v tomto článku.

Jazyk je rozdělen na následující prvky:

Skalární výrazy, které vytvářejí skalární hodnoty. Skalární výrazy zahrnují predikátové řetězcové výrazy, relační výrazy a aritmetické výrazy.
Skalární funkce, které vracejí skalární hodnoty.
Agregační výrazy, které se používají k dělení kolekcí událostí a výpočetních měr na oddíly.
Klauzule, které tvoří základní komponenty dotazů JSON nebo část výrazu.

Datový model

Rozhraní API pro dotazy Azure Time Series Insights Gen1 pracuje s daty, která jsou uložená jako jednotlivé události v prostředí. Každá událost je sada dvojic název vlastnosti a hodnota .

Vlastnosti události

Vlastnosti události můžou mít jeden z následujících primitivních typů: Bool, DateTime, Double nebo String. Všechny primitivní typy mají hodnotu null.

Poznámka

Přizpůsobené formáty zdroje událostí můžou podporovat větší sadu typů hodnot. Azure Time Series Insights Gen1 odvodí nejbližší primitivní typ a pak na ně přetypuje přizpůsobené typy při příchozím přenosu dat.

Všechny události mají následující předdefinované vlastnosti s předdefinovaným názvem a typem:

Název vlastnosti	Typ vlastnosti	Definice
$ts	Datum a čas	Časové razítko události
$esn	Řetězec	Název zdroje událostí

Časové razítko události

Ve výchozím nastavení zdroj události poskytuje hodnotu časového razítka události. Například události pocházející z centra IoT by měly čas zařazení do fronty jako časové razítko.

Zákazníci můžou toto chování změnit tak, že místo toho nakonfigurují jinou vlastnost události. Vlastní vlastnosti časového razítka je možné zadat ve službě Event Hubs a IoT Hubs.
Název zdroje událostí

Název zdroje událostí je název, který se zobrazí pro zdroj události, ze kterého Azure Time Series Insights Gen1 přijal událost. Názvy zdrojů událostí jsou přidruženy ke konkrétní události v době příchozího přenosu dat.
Důležité
- Názvy zdrojů událostí zůstávají po celou dobu životnosti události beze změny.
- Pokud se název zdroje událostí změní, existující události budou mít starý název zdroje událostí. Nové události budou mít nový název zdroje událostí.

Typy událostí

Vlastní vlastnosti událostí jsou jedinečně identifikovány a odkazovány ve výrazech dotazu podle názvu a typu. Událost může mít více než jednu vlastnost se stejným názvem a různými typy. Vlastnosti se stejným názvem, ale různými typy můžou být výsledkem rozdělení typu příchozího přenosu dat.

Hodnota vlastnosti události typu Řetězec může být uložena jako vlastnost s jiným typem v následujících případech:

Pokud je hodnota String platná dvojitá hodnota, uloží se jako Double i String.
Pokud je hodnota String platná hodnota DateTime , uloží se pouze jako DateTime .

Rozhraní API pro dotazy převede prázdné řetězcové literály ("") ve výstupu na null .

Azure Time Series Insights Gen1 má omezenou podporu následujících hodnot v rámci typu Double: Double.NaN, Double.PositiveInfinitya Double.NegativeInfinity. Tyto hodnoty jsou převedeny na null během příchozího přenosu dat, ale pokud vyhodnocení dotazu vytvoří jednu z těchto hodnot, hodnota se vyhodnotí a serializuje jako řetězec v odpovědi.

Tyto hodnoty můžete předat jako řetězce pro příchozí přenos dat, takže ve výrazech dotazu by se tyto hodnoty měly předávat také jako řetězce.

Schémata událostí popisují vlastnosti události. Schéma události obsahuje název zdroje události a uspořádanou sadu vlastností události. Různé události můžou mít různá schémata nebo sdílet stejné schéma.

Skalární výrazy

Skalární výrazy vytvářejí skalární hodnoty. Skalární výrazy jsou rozdělené do následujících typů:

Výrazy konstant
Výrazy odkazu na vlastnosti
Porovnávací výrazy
Aritmetické výrazy
Řetězcové výrazy predikátu

Výrazy konstant

Konstantní výrazy představujete pomocí následujících literálů pro každý z primitivních typů:

Primitivní typ	Reprezentace JSON	Příklad JSON	Poznámky
Bool	Jako logický typ JSON	`true`, `false`
Datum a čas	Jako vnořený objekt s jednou vlastností dateTime ve formátu `yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK`ISO 8601 .	`{"dateTime":"2016-08-01T00:00:00.000Z"}`
dvojité	Přetypování čísla JSON do oblasti Double	`1.23e45`, `123`	Dvojité přetečení vygeneruje chybu.
Řetězec	Typ řetězce JSON	`"abc"`
TimeSpan	Jako vnořený objekt s jednou vlastností timeSpan ve formátu ISO 8601 : `P[n]Y[n]M[n]DT[n]H[n]M[n]S`.	`{"timeSpan":"P1Y2M3DT4M5.67S"}`

Primitivní typy s možnou hodnotou null

Primitivní datové typy mají hodnotu null. null Hodnoty primitivních typů se ve formátu JSON vyjadřují následujícím způsobem:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Výrazy odkazu na vlastnosti

Výraz odkazu na vlastnost slouží k přístupu k hodnotám nedefinovaných vlastností události. Jiné než předdefinované vlastnosti zahrnují všechny přizpůsobené vlastnosti nad rámec výchozích vlastností, které jsou automaticky obsaženy ve schématu událostí.

Typ výsledku výrazu odkazu na vlastnost je primitivním typem vlastnosti. Vlastnosti ve schématu událostí jsou jednoznačně identifikovány názvem a typem a referenční výraz vyžaduje zadání obou.

Příklady JSON:

{
   "property": "p1",
   "type": "Bool"
}

{
   "property": "p1",
   "type": "DateTime"
}

{
   "property": "p1",
   "type": "Double"
}

{
   "property": "p1",
   "type": "String"
}

{
   "property": "p1",
   "type": "TimeSpan"
}

Předdefinovaný výraz odkazu na vlastnosti se používá pro přístup k předdefinovaných vlastnostem události. Předdefinované vlastnosti jsou pouze ty vlastnosti, které jsou automaticky definovány ve schématu událostí.

Typ výsledku předdefinované výrazu odkazu na vlastnost je primitivním typem vlastnosti. Předdefinované vlastnosti jsou odkazovány pouze podle názvu; proto není v referenčním výrazu potřeba žádný typ:

{ "builtInProperty": "$esn" }

Porovnávací výrazy

Podporují se následující logické porovnávací výrazy:

Název vlastnosti ve formátu JSON	Description
eq	Je rovno
In	In (rovná se libovolnému)
Fráze	Obsahuje frázi.
Startswith	Začíná na
Endswith	Končí frází
Regex	Odpovídá regulárnímu výrazu.
lt	Menší než
Lte	Menší než nebo rovno
gt	Větší než
Gte	Větší než nebo rovno

Důležité

Všechny porovnávací výrazy přebírají primitivní typy argumentů z levé i pravé strany a vrací logickou hodnotu představující výsledek porovnání.
Oba typy argumentů na levé straně a na pravé straně v porovnání by se měly shodovat.
Všechny typy se implicitně přetypují jenom na sebe a explicitní přetypování nejsou podporována.

{
  "eq": {
    "left": {
      "property": "p1",
      "type": "String"
     },
     "right": "abc"
  }
}

Příklady JSON:

{
   "startsWith": {
     "left": {
       "property": "p1",
       "type": "String"
      },
      "right": "abc"
   }
}

{
   "startsWith": {
     "left": {
       "property": "p1",
       "type": "String"
     },
     "right": "",
     "stringComparison": "Ordinal"
   }
}

{
   "endsWith": {
     "left": {
       "property": "p1",
       "type": "String"
     },
     "right": {
       "property": "p2",
       "type": "String"
     },
     "stringComparison": "Ordinal"
   }
}

Následující tabulka uvádí podporované typy argumentů pro jednotlivé výrazy porovnání:

Typ argumentu	Podporovaná operace porovnání
Bool	eq, in
Datum a čas	eq, in, lt, lte, gt, gte
dvojité	eq, in, lt, lte, gt, gte
Řetězec	eq, in, phrase, startsWith, endsWith, regex
TimeSpan	eq, in, lt, lte, gt, gte

Literál NULL lze použít pouze s následujícími relačními operátory: eq nebo in.

Výsledkem operátorutrue eq je, že obě strany představují null hodnoty. V opačném případě výsledkem operátoru je false.
U jiných operací je vyvolána chyba pro literál NULL a chování je nedefinované pro vlastnosti s hodnotou null (jakákoli operace porovnání, která má za falsenásledek ).
Hodnota null předchází hodnotám, které nejsou null, v pořadí řazení (například pokud se pro vrácení seznamu událostí použije řazení podle vlastnosti).

Azure Time Series Insights Gen1 podporuje následující logické výrazy:

Název vlastnosti ve formátu JSON	Description
and	Vezme neprázdnou sadu logických argumentů a vrátí `true` , pokud se všechny vyhodnotí jako `true`.
Nebo	Vezme neprázdnou sadu logických argumentů a vrátí `true` , pokud se některý z nich vyhodnotí jako `true`.
Ne	Vezme jeden logický argument a vrátí jeho negovanou hodnotu.

{
  "and": [
    {
      "eq": {
        "left": {
          "property": "p1",
          "type": "String"
        },
        "right": "abc"
      }
    },
    {
      "not": {
        "lt": {
          "left": {
            "property": "p1",
            "type": "Double"
          },
          "right": 1
        }
      }
    }
  ]
}

Vlastnost stringComparison je volitelná. Ve výchozím nastavení je OrdinalIgnoreCasejeho hodnota , což způsobí, že se při porovnávání ignoruje velká a velká písmena vět.

{
  "regex": {
    "left": {
      "property": "p1",
      "type": "String"
    },
    "right": "^abc*"
  }
}

{
  "regex": {
      "left": "abc",
      "right": "^a*$"
  }
}

Aritmetické výrazy

Azure Time Series Insights Gen1 podporuje následující aritmetické výrazy:

Název vlastnosti ve formátu JSON	Description
add	Sčítání
Dílčí	Odčítání
Mult	Násobení
div	Oddělení

Všechny aritmetické výrazy přebírají levé a pravé argumenty primitivních typů a vrátí hodnotu, která představuje výsledek operace.

Všechny typy se implicitně přetypují jenom na sebe a explicitní přetypování nejsou podporována.

{
  "add": {
    "left": {
      "property": "p1",
      "type": "Double"
     },
     "right": 1
  }
}

Následující tabulka uvádí podporované typy argumentů pro každý z aritmetických výrazů:

Operace	Levý typ	Pravý typ	Typ výsledku
add	dvojité	dvojité	dvojité
add	TimeSpan	TimeSpan	TimeSpan
add	Datum a čas	TimeSpan	Datum a čas
add	TimeSpan	Datum a čas	Datum a čas
Dílčí	dvojité	dvojité	dvojité
Dílčí	TimeSpan	TimeSpan	TimeSpan
Dílčí	Datum a čas	Datum a čas	TimeSpan
Dílčí	Datum a čas	TimeSpan	Datum a čas
mul	dvojité	dvojité	dvojité
div	dvojité	dvojité	dvojité

Řetězcové výrazy predikátu

Logické predikátové řetězcové výrazy obsahují logické predikáty, které jsou reprezentovány jako čitelné výrazy označované jako predikátové řetězce.

Příklady řetězců predikátu:

Predikátový řetězec	Description
`Description HAS 'hello world'`	`true` pro události, které obsahují frázi `hello world` ve vlastnosti Description ve všech zdrojích událostí
`'hello world'`	`true` pro události, které obsahují frázi `hello world`
`startsWith(Status, 'go')`	`true` pro události se stavem začínajícím na `go`
`endsWith(Status, 'oD')`	`true` pro události se stavem končícím na `od`
`startsWith_cs(Status, 'Go')`	`true` pro události se stavem začínajícím na `Go`
`endsWith_cs(Status, 'od')`	`true` pro události se stavem začínajícím na `od`
`matchesRegex(s, '^G*')`	`true` pro události se stavem , který odpovídá regulárnímu výrazu `^G*`
`PointValue.Double = 3.14`	`true` pro události s dvojitou hodnotou PointValue rovnou `3.14`
`Status IN ('Good','Bad')`	`true` pro události se stavem , které obsahují `Good` nebo `Bad`
`PointValue > 3.14 AND Status.String = 'Good'`	`true`pro události s hodnotou PointValue větší než `3.14`a stav řetězce`Good`
`[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'`	`true` pro události s hodnotou PointValue větší než `3.14` a Stav`Good` nebo `Bad` a Popis neobsahující frázi `hello world`

{ "predicateString": "PointValue.Double = 3.14" }

Výraz v řetězci predikátu se vyhodnotí jako logický výraz JSON. Měl by splňovat následující (zjednodušenou) gramatiku:

Logický výraz JSON	Backus–Naur form
`parse`	`orPredicate EOF \| EOF;`
`orPredicate`	`andPredicate (Or andPredicate)*;`
`andPredicate`	`notPredicate (And notPredicate)*;`
`notPredicate`	`(Not)* predicate;`
`predicate`	`parenPredicate \| comparisonPredicateExtended \| hasPredicate \| inPredicate;`
`parenPredicate`	`OpenParen orPredicate CloseParen;`
`parenExpression`	`OpenParen additiveExpression CloseParen;`
`comparisonPredicateExtended`	`(ComparisonOp literal) \| comparisonPredicate;`
`comparisonPredicate`	`additiveExpression ComparisonOp additiveExpression;`
`additiveExpression`	`multiplicativeExpression ((Plus \| Minus) multiplicativeExpression)*;`
`multiplicativeExpression`	`unaryExpression (MultiplicativeOp unaryExpression)*;`
`functionCallExpression`	`identifier OpenParen CloseParen;`
`unaryExpression`	`identifier \| literal \| functionCallExpression \| parenPredicate \| parenExpression;`
`hasPredicate`	`(identifier? Has)? StringLiteral;`
`inPredicate`	`identifier? In OpenParen literal (Comma literal)* CloseParen;`
`literal`	`StringLiteral \| ((Minus)? NumericLiteral) \| BooleanLiteral \| DateTimeLiteral \| TimeSpanLiteral \| NullLiteral;`
`identifier`	`BuiltinIdentifier \| (QuotedOrUnquotedIdentifier (Sep QuotedOrUnquotedIdentifier)?);`

Azure Time Series Insights primitivní datové typy Gen1 jsou podporovány ve výrazech predikátu řetězců.

Na rozdíl od referenčních výrazů vlastností JSON je možné typ vlastnosti vynechat. V takovém případě se typ automaticky odvodí.

Podporované literály

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

Podporované typy operandů

Operace	Podporované typy	Poznámky
<, >, <=, >=	Double, DateTime, TimeSpan
=, !=, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> je ekvivalent pro !=
+, -, *, /	Double, DateTime, TimeSpan
IN	String, Bool, Double, DateTime, TimeSpan, NULL	Všechny operandy by měly být stejného typu nebo měly mít hodnotu NULL . Několik hodnot NULLodpovídá jedné hodnotě NULL.
HSA	Řetězec	Na pravé straně jsou povoleny pouze literály konstantního řetězce. Prázdný řetězec a hodnota NULL nejsou povoleny.

Pro porovnání predikáty (<, >, =<, >=, =! =) a operand predikátu IN může mít hodnotu NULL nebo jeden typ.

U výrazů s predikátem HAS lze konstantní literál na pravé straně operandu HAS rozšířit do více typů. Kromě toho se konstantní literál na pravé straně operandu HAS analyzuje na hodnotu Bool, Double, DateTime nebo TimeSpan . Pro každou úspěšně parsovanou hodnotu se vytvoří predikát s operátorem = . Tyto predikáty a původní predikát HAS jsou spojeny do predikátu OR . Například řetězec p1 HAS '1.0' predikátu je ekvivalentem p1.String HAS '1.0' OR p1.Double = 1.0, pokud existují vlastnosti p1 s typy String a Double .

Kontrola typu

Predikátové výrazy se kontrolují a ověřují, aby se zajistilo, že se pravý a levý typ shodují.

Důležité

Pokud se konstanty vlevo a vpravo od operandu neshodují, vyvolá se chyba.
Chyba se vyvolá také v případě, že operace není povolena u konkrétních typů nebo mezi těmito typy.

Pokud je pro vlastnost zadaný typ, použije se kontrola typu:

Proti literálu NULL se akceptuje libovolný typ vlastnosti.

V opačném případě by se typy levé a pravé strany měly shodovat.

Příklady vlastností p1 a p2 typu String a vlastnost p3 typu Double jsou uvedeny v následující tabulce:

Predikátový řetězec	Je platný?	Poznámky
`p1.String = 'abc'`	Yes
`p1.String = p2.String`	Yes
`p1.String = NULL`	Ano	`NULL` odpovídá libovolnému typu levé strany.
`p3.Double = 'abc'`	Ne	Neshoda typů.
`p3.Double = p1.String`	Ne	Neshoda typů.
`p1.String HAS 'abc'`	Yes
`p3.Double HAS '1.0'`	Ano	Řetězcový literál se úspěšně parsoval na hodnotu Double .

Pokud je pro vlastnost vynechán typ, ale je zadán název, proveďte následující kroky:

Všechny vlastnosti se zadaným názvem a typy jsou převzaty.
Operandy na levé a pravé straně jsou seskupené do dvojic podle typu.
Páry jsou zřetězeny pomocí operací AND .

Příklady vlastností p1 a p2 typů String a Double a některé jejich ekvivalenty jsou uvedeny v následující tabulce:

Predikátový řetězec	Ekvivalentní řetězec predikátu silného typu	Poznámky
`p1 = 'abc'`	`p1.String = 'abc'`
`p1 = true`		Žádná vlastnost p1 typu Bool, takže se vygeneruje chyba chybějící vlastnosti.
`p1 = NULL`	`p1.String = NULL AND p1.Double = NULL`	U `NULL` pravé strany se předpokládá, že všechny odpovídající vlastnosti by měly být `NULL`.
`p1 != NULL`	`p1.String != NULL OR p1.Double != NULL`	Toto je inverze předchozího výrazu.
`p1 = '1.0'`	`p1.String = '1.0'`
`p1 IN (1.0, NULL)`	`p1.Double = 1.0 OR p1.Double = NULL`
`p1 IN (NULL)`	`p1.String = NULL AND p1.Double = NULL`	Jedná se o ekvivalent .`p1 = NULL`
`p1 HAS '1.0'`	`p1.String HAS '1.0' OR p1.Double = 1.0`	Řetězcový literál byl úspěšně analyzován na platnou hodnotu Double .
`p1 HAS 'true'`	`p1.String HAS 'true'`	Řetězcový literál se úspěšně parsoval na bool, ale ne p1. Logická vlastnost existuje.
`p1 = p2`	`p1.String = p2.String AND p1.Double = p2.Double`
`p1 != p2`	`p1.String != p2.String OR p1.Double != p2.Double`	Toto je inverze předchozího výrazu.

Název vlastnosti i typ lze u vlastnosti na levé straně vynechat, pokud je typ vlastnosti na pravé straně správně definovaný. To platí vždy, když má pravá strana konstantní literály a neobsahuje jenom NULL literál.

Tento scénář je zobecnění fulltextového vyhledávání, které používá operand HAS .
Všechny vlastnosti, které odpovídají typu na pravé straně, jsou převzaty a výsledné výrazy jsou zřetězeny prostřednictvím operace OR .

Příklady vlastnosti p1 typů String a Double a vlastnost p2 typů String a DateTime jsou uvedeny v následující tabulce:

Řetězec predikátu	Ekvivalentní řetězec predikátu silného typu	Poznámky
`= 'abc'`	`p1.String = 'abc' OR p2.String = 'abc'`
`!= 'abc'`	`p1.String != 'abc' AND p2.String != 'abc'`	Inverze předchozího výrazu
`= 1.0`	`p1.Double = 1.0`
`= dt'2000-01-02T03:04:05'`	`p2.DateTime = dt'2000-01-02T03:04:05'`
`= true`		Chyba Neexistuje žádná logická vlastnost, takže se vygeneruje chyba chybějící vlastnosti.
`= NULL`		Chyba Vynechání názvu vlastnosti pro `NULL` pravou stranu není povoleno.
`IN (NULL)`		Stejné jako u předchozí chyby.
`IN (1.0, NULL)`	`p1.Double = 1.0 OR p1.Double = NULL`
`HAS '1.0'`	`p1.String HAS '1.0' OR p1.Double = 1.0 OR p2.String HAS '1.0'`
`HAS 'true'`	`p1.String HAS 'true' OR p2.String HAS 'true'`	Neexistuje žádná vlastnost typu Bool.

Pokud je operátor vynechán společně s názvem vlastnosti, HAS operace se předpokládá.

Skalární funkce

Skalární funkce vrací skalární hodnoty.

Nativní funkce

Mezi skalární funkce, které Azure Time Series Insights Gen1 podporuje, patří:

Název funkce	Vrácená hodnota	Argumenty	Příklad	Poznámky
UtcNow	Datum a čas	Žádné	utcNow()	Vrátí aktuální čas ve formátu UTC. V názvu funkce se rozlišují velká a malá písmena.

Funkce UTC teď vrátí hodnotu DateTime , která obsahuje aktuální čas ve formátu UTC. Nepřijímá žádné argumenty.

Agregační výrazy

Agregační výrazy se používají k rozdělení kolekcí událostí a výpočetních měr na oddíly. Agregační výrazy jsou rozdělené do následujících druhů:

Výrazy dimenzí
Výrazy jedinečných hodnot
Výrazy histogramu data
Výrazy měr

Výrazy dimenzí

Výrazy dimenze v klauzuli aggregates slouží k rozdělení sady událostí a přiřazení skalárního klíče každému oddílu.

Typy výrazů dimenzí:

Název vlastnosti ve formátu JSON	Popis	Příklad
jedinečné hodnoty	Hodnoty dimenzí ve výsledku jsou přesné hodnoty dané vlastnosti.
dateHistogram	Hodnoty dimenzí ve výsledku jsou časové rozsahy dané vlastnosti.	Histogram data časového razítka může mít za následek 10 1hodinových rozsahů hledání.
numericHistogram	Hodnoty dimenzí ve výsledku jsou rozsahy hodnot v dané vlastnosti.	Výsledkem číselného histogramu teploty může být návrat o 10 stupňů.

Azure Time Series Insights Gen1 omezuje maximální kardinalitu neboli maximální velikost mřížky vstupního agregovaného dotazu na 150 000 buněk. Při výpočtu kardinality agregovaného dotazu vynásobíte velikosti všech dimenzí v dotazu. Pokud je produkt menší než 150 000, dotaz se přijme ke spuštění. Pokud je součin roven nebo menší než 150 000, dotaz se zamítne.

Maximální velikost dimenze, která se vytváří pomocí uniqueValues a numericHistogramu , určíte pomocí klauzule take . V dateHistogramu se velikost vypočítá vydělením rozsahu hledání velikostí intervalu dateHistogram , který určíte pomocí klauzule breaks .

Například agregační dotaz má rozsah hledání nastavený od 2017-11-15T16:00:00.000Z na 2017-11-15T19:00:00.000Z = 3 hodiny. Pokud dotaz obsahuje dateHistogram s klauzulí breaks nastavenou na 1 minutu (dimenze 1) a uniqueValues nad vlastností XYZ, velikost dimenze dateHistogramu je 3x60=180. Tento výsledek znamená, že hodnoty uniqueValues mohou trvat až 150 000/180 = celkem 833 položek.

Výrazy jedinečných hodnot

Výraz jedinečných hodnot slouží k seskupení sady událostí podle hodnot zadané vlastnosti události.

Výsledkem vyhodnocení tohoto výrazu JSON je až 100 záznamů, které jsou seskupené podle sensorId vlastnosti String.

{
  "uniqueValues": {
    "input": {
      "property": "sensorId",
      "type": "String"
    },
    "take": 100
  }
}

Výrazy histogramu data

Výraz histogramu data se používá k seskupení hodnot vlastností DateTime do kbelíků zadané velikosti.

Výsledkem vyhodnocení tohoto výrazu JSON je sada záznamů časového razítka , které jsou zaokrouhlené tak, že každá hodnota má vynulované sekundy.

{
  "dateHistogram": {
    "input": {
      "builtInProperty": "$ts"
    },
    "breaks": {
      "size": "1m"
    }
  }
}

Číselné výrazy histogramu

Pomocí číselného výrazu histogramu můžete seskupit hodnoty vlastnosti Double do zadaného počtu kbelíků.

Výsledkem vyhodnocení tohoto výrazu JSON je 10 záznamů, takže rozsah mezi minimálními a maximálními hodnotami vlastnosti p1 je rozdělen do 10 kbelíků.

{
  "numericHistogram": {
    "input": {
      "property": "p1",
      "type": "Double"
    },
    "breaks": {
      "count": 10
    }
  }
}

Výrazy měr

Výrazy míry v klauzulích agregace se používají k výpočtu skalární hodnoty u sady událostí. Výraz míry je například výpočet maximální hodnoty naměřené senzorem teploty za posledních 24 hodin.

K výpočtu počtu událostí v odpovídajícím kbelíku se používá výraz count .

{ "count": {} }

Pomocí výrazů min, max, avg a sum můžete vypočítat minimum, maximum, průměr a součet hodnot pro zadanou vlastnost v rámci odpovídajícího kbelíku.

{
  "min": {
    "input": {
      "property": "temperature",
      "type": "Double"
    }
  }
}

Pomocí výrazů první a poslední míry můžete získat hodnotu zadané vlastnosti A , která odpovídá minimální nebo maximální hodnotě vlastnosti B.

{
  "first": {
    "input": {
      "property": "propertyA",
      "type": "String"
    },
    "orderBy": {
      "property": "propertyB",
      "type": "Double"
    }
  }
}

{
  "last": {
    "input": {
      "property": "propertyA",
      "type": "Double"
    },
    "orderBy": {
      "property": "propertyB",
      "type": "DateTime"
    }
  }
}

Klauzule orderBy je volitelná a ve výchozím nastavení používá vlastnost Timestamp$ts. Vstup může být libovolného typu. Klauzule orderBy podporuje pouze typy Double a DateTime .

Pokud je vlastnost B typu DateTime , získáte nejnovější nebo nejstarší hodnotu vlastnosti A.

Pomocí prvního a posledního výrazu můžete porozumět nejstarší nebo nejnovější hodnotě konkrétní vlastnosti. Pokud máte například vlastnost s názvem deviceID a chcete porozumět nejnovějšímu deviceID odeslání události, je last nejúčinnějším operátorem výrazu, který můžete použít k identifikaci dané informace.

{
  "last": {
    "input": {
      "property": "deviceID",
      "type": "String"
    }
  }
}

Dalším příkladem je použití funkce last k vyhledání posledního nahlášeného umístění konkrétního objektu, jako je loď, vozidlo nebo jiný pohybující se objekt.

Pro ilustraci dotazu, který vytvoří poslední známou polohu lodí ve flotile, můžete vytvořit dotaz podobný tomuto:

{
  "searchSpan": {
    "from": "2018-05-05T12:00:00.000Z",
    "to": "2018-05-15T12:01:00.000Z"
  },
  "aggregates": [
     {
       "dimension": {
         "uniqueValues": {
           "input": {
             "property": "shipId",
             "type": "string"
            },
            "take": 150000
          }
        },
        "measures": [
          {
            "last": {
              "input": {
                "property": "Latitude",
                "type": "Double"
              }
           }
        },
        {
          "last": {
            "input": {
              "property": "Longitude",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Dalším příkladem je první použití k vyhledání zařízení, které hlásí nejnižší tlak pro každou továrnu:

{
  "searchSpan": {
    "from": "2018-05-05T12:00:00.000Z",
    "to": "2018-05-15T12:01:00.000Z"
  },
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "plantId",
            "type": "String"
          },
          "take": 150000
        }
     },
     "measures": [
       {
         "first": {
           "input": {
             "property": "deviceId",
             "type": "String"
           },
           "orderBy": {
             "property": "pressure",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Podpora dimenzí a typů měr

Tady jsou podporované výrazy dimenzí a měr založené na typu vlastnosti:

Typ vlastnosti	Podporované výrazy dimenzí	Podporované výrazy měr
Bool	`"uniqueValues"`	`"first"` (vstup), `"last"` (vstup)
Datum a čas	`"uniqueValues"`, `"dateHistogram"`	`"min"`, `"max"`, `"first"` (orderBy, input), `"last”` (orderBy, input)
dvojité	`"uniqueValues"`, `"numericHistogram"`	`"sum"`, `"avg"`, `"min"`, `"max"`, ( `"first"` orderBy, input), `"last”` (orderBy, input)
Řetězec	`"uniqueValues"`	`"first"` (vstup), `"last"` (vstup)

Klauzule

Klauzule tvoří základní komponenty dotazů JSON nebo části výrazu. Klauzule jsou rozděleny do následujících typů:

Klauzule rozsahu vyhledávání
Predikátové klauzule
Horní klauzule omezení
Klauzule limitu take
Omezení ukázkových klauzulí
Zalomení klauzulí
Klauzule Agregace

Klauzule rozsahu vyhledávání

Pomocí klauzule search span můžete filtrovat integrovanou vlastnost časového razítka události na daný interval. Začátek intervalu je včetně. Konec intervalu je výhradní.

{
  "searchSpan": {
    "from": {
      "dateTime": "2016-08-01T00:00:00.000Z"
    },
    "to": {
      "dateTime": "2016-08-31T00:00:00.000Z"
    }
  }
}

Vlastnosti z a do v klauzuli search span (searchSpan) by měly být platnými výrazy typu výsledku DateTime . Tyto výrazy se vyhodnocují před spuštěním dotazu, což znamená, že by neměly obsahovat žádné odkazy na vlastnosti.

Predikátové klauzule

Klauzule predikátu slouží k filtrování událostí, které splňují predikát. Měl by se přeložit na logický výraz.

{
  "predicate": {
    "eq": {
      "left": {
        "property": "p1",
        "type": "String"
       },
       "right": "abc"
     }
  }
}

Filtrování událostí znamená spuštění predikátu, který je reprezentován logickým výrazem pro každou událost v prostředí. Spuštění výrazu u události se vrátí true , pokud událost musí být zahrnuta do dalších operací. Vrátí, false pokud je nutné vynechat událost z dalšího zpracování.

Poznámka

Události se vždy filtrují podle rozsahu hledání kromě filtrování zadaného ve výrazu predikátu.

Horní klauzule omezení

Horní klauzuli *limitu můžete použít k získání zadaného počtu hodnot ve vzestupném nebo sestupném pořadí. Počet hodnot je omezený podle zadaného počtu.

{
  "sort": [
    {
      "input": {
        "builtInProperty": "$ts"
      },
      "order": "Asc"
    }
  ],
  "count": 10
}

Klauzule limitu take

Klauzuli limit take můžete použít jako rychlý způsob, jak získat sadu hodnot bez konkrétního pořadí. Počet vrácených hodnot je omezen zadaným vstupem.

{ "take": 10 }

Omezení ukázkových klauzulí

K získání statisticky reprezentativního vzorku ze sady hodnot použijete klauzuli *limit sample . Počet vrácených hodnot je omezen zadaným vstupem.

{ "sample": 10 }

Zalomení klauzulí

Pomocí klauzule *break ve výrazech histogramu určíte, jak má být oblast rozdělena.

U histogramů kalendářních dat byste měli zadat velikost intervalu data a času a jeho hranic. Provedete to, pokud histogram není založený na integrované vlastnosti časového razítka , kde jsou hranice určeny na základě rozsahu hledání:

Hranice intervalů jsou volitelné a je možné je použít. Můžete je například použít, pokud jsou určeny na základě rozsahu hledání, pokud jsou vynechány hranice intervalu.
U číselných histogramů byste měli zadat počet konců. Hranice intervalu určíte na základě minimální a maximální hodnoty vlastnosti.

{
  "breaks": {
    "size": "1d",
    "from": "2000-01-02T03:04:05.0000000",
    "to": "2000-01-02T03:04:05.0000000"
  }
}

{
  "breaks": {
    "count": 10
  }
}

Klauzule Agregace

Klauzuli aggregates použijete k rozdělení sady událostí podle dané vlastnosti při měření hodnot jiných vlastností událostí.

Míry se vyhodnocují na každém oddílu vytvořeném výrazem dimenze.

Následující příklad JSON vypočítá průměrné, minimální a maximální teploty na ID senzoru.

{
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "sensorId",
            "type": "String"
          },
          "take": 100
        }
      },
      "measures": [
        {
          "avg": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        },
        {
          "min": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        },
        {
          "max": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Poznámka

Klauzule aggregates je pole, které umožňuje zadat více než jednu agregaci na nejvyšší úrovni.

Následující příklad JSON vypočítá průměrnou teplotu podle města a výrobce nezávisle na sobě:

{
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "city",
            "type": "String"
          },
          "take": 100
        }
      },
      "measures": [
        {
          "avg": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        }
      ]
    },
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "manufacturer",
            "type": "String"
          },
          "take": 100
        }
      },
      "measures": [
        {
          "avg": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Poznámka

Použití více než jednoho prvku v agregačním poli se v současné době nepodporuje.
Definice agregace však může obsahovat vnořené pole, které určuje flexibilnější multidimenzionální mřížku.

Následující příklad JSON vypočítá průměrnou teplotu na ID senzoru za minutu.

{
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "sensorId",
            "type": "String"
          },
          "take": 100
        }
      },
      "aggregate": {
        "dimension": {
          "dateHistogram": {
            "input": {
              "builtInProperty": "$ts"
            },
            "breaks": {
              "size": "1m"
            }
          }
        },
        "measures": [
          {
            "avg": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          }
        ]
      }
    }
  ]
}

Viz také

Další informace o rozhraních API Azure Time Series Insights Gen1 najdete v tématu Rozhraní API gen1.
Další informace o parametrech požadavků a ověřování najdete v tématu Ověřování a autorizace.
Další informace o Azure Time Series Insights Gen1 najdete v dokumentaci k Gen1.

Sdílet prostřednictvím

syntaxe dotazu Azure Time Series Insights Gen1

Souhrn

Datový model

Vlastnosti události

Typy událostí

Skalární výrazy

Výrazy konstant

Primitivní typy s možnou hodnotou null

Výrazy odkazu na vlastnosti

Porovnávací výrazy

Aritmetické výrazy

Řetězcové výrazy predikátu

Podporované literály

Podporované typy operandů

Kontrola typu

Skalární funkce

Nativní funkce

Agregační výrazy

Výrazy dimenzí

Výrazy jedinečných hodnot

Výrazy histogramu data

Číselné výrazy histogramu

Výrazy měr

Podpora dimenzí a typů měr

Klauzule

Klauzule rozsahu vyhledávání

Predikátové klauzule

Horní klauzule omezení

Klauzule limitu take

Omezení ukázkových klauzulí

Zalomení klauzulí

Klauzule Agregace

Viz také

Další materiály