Azure Time Series Insights Gen1-querysyntaxis

Waarschuwing

Dit is een Gen1-artikel.

In dit artikel worden de indeling en syntaxis van de queryaanvraag voor de Azure Time Series Insights Gen1-query-API beschreven.

Samenvatting

Belangrijk

• Queryaanvragen moeten de JSON-indeling hebben.
• Nettoladingen van HTTP-aanvragen die naar de query-API worden gemaakt, moeten voldoen aan de indeling die in dit artikel is opgegeven.

De taal is onderverdeeld in de volgende elementen:

• Scalaire expressies, die scalaire waarden produceren. Scalaire expressies omvatten predicaattekenreeksexpressies, vergelijkingsexpressies en rekenkundige expressies.
• Scalaire functies, die scalaire waarden retourneren.
• Aggregatie-expressies, die worden gebruikt voor het partitioneren van verzamelingen van gebeurtenissen en rekenmetingen over de partities.
• Componenten, die de samenstellende onderdelen van JSON-query's of een deel van een expressie vormen.

Gegevensmodel

De Azure Time Series Insights Gen1 Query-API werkt op gegevens die zijn opgeslagen als afzonderlijke gebeurtenissen in een omgeving. Elke gebeurtenis is een set eigenschapsnaam - en waardeparen .

Gebeurteniseigenschappen

Gebeurteniseigenschappen kunnen van een van de volgende primitieve typen zijn: Bool, DateTime, Double of String. Alle primitieve typen kunnen null worden gebruikt.

Notitie

Aangepaste gebeurtenisbronindelingen ondersteunen mogelijk een grotere set waardetypen. Azure Time Series Insights Gen1 leid het dichtstbijzijnde primitieve type af en cast vervolgens aangepaste typen naar deze typen bij inkomend verkeer.

Alle gebeurtenissen hebben de volgende ingebouwde eigenschappen met een vooraf gedefinieerde naam en type:

Naam van eigenschap	Eigenschapstype	Definitie
$ts	Datum/tijd	Tijdstempel van gebeurtenis
$esn	Tekenreeks	Naam van gebeurtenisbron

• Tijdstempel van gebeurtenis

  Standaard wordt een tijdstempelwaarde voor gebeurtenissen opgegeven door de gebeurtenisbron. Gebeurtenissen die afkomstig zijn van een IoT-hub, hebben bijvoorbeeld hun enqueued tijd als een tijdstempel.

  Klanten kunnen dit gedrag wijzigen door in plaats daarvan een andere gebeurteniseigenschap te configureren. Aangepaste tijdstempeleigenschappen kunnen worden opgegeven in Event Hubs en IoT-hubs.

• Naam van gebeurtenisbron

  De naam van de gebeurtenisbron is de naam die wordt weergegeven voor de gebeurtenisbron waarvan Azure Time Series Insights Gen1 de gebeurtenis heeft ontvangen. Namen van gebeurtenisbronnen zijn gekoppeld aan een bepaalde gebeurtenis op het moment van inkomend verkeer.

  Belangrijk

  • Namen van gebeurtenisbronnen blijven ongewijzigd gedurende de levensduur van de gebeurtenis.
  • Als de naam van een gebeurtenisbron wordt gewijzigd, dragen bestaande gebeurtenissen de oude naam van de gebeurtenisbron. Nieuwe gebeurtenissen dragen de naam van de nieuwe gebeurtenisbron.

Gebeurtenistypen

Aangepaste gebeurteniseigenschappen worden uniek geïdentificeerd en waarnaar wordt verwezen in query-expressies op naam en type. Een gebeurtenis kan meer dan één eigenschap met dezelfde naam en verschillende typen hebben. Eigenschappen met dezelfde naam, maar verschillende typen, kunnen het gevolg zijn van het splitsen van het type inkomend verkeer.

Een gebeurteniseigenschapswaarde van het type Tekenreeks kan in de volgende gevallen worden opgeslagen als een eigenschap met een ander type:

• Als een tekenreekswaarde een geldige dubbele waarde is, wordt deze opgeslagen als dubbel en tekenreeks.
• Als een tekenreekswaarde een geldige Datum/ tijd-waarde is, wordt deze alleen opgeslagen als Datum/ tijd.

De Query-API converteert lege letterlijke tekenreeksen ("") naar null in de uitvoer.

Azure Time Series Insights Gen1 biedt beperkte ondersteuning voor de volgende waarden binnen het type Double: Double.NaN, Double.PositiveInfinityen Double.NegativeInfinity. Deze waarden worden tijdens inkomend verkeer geconverteerd naar null , maar als de query-evaluatie een van deze waarden produceert, wordt de waarde geëvalueerd en geserialiseerd als een tekenreeks als antwoord.

U kunt deze waarden doorgeven als Tekenreeksen voor inkomend verkeer, dus in query-expressies moeten deze waarden ook worden doorgegeven als tekenreeksen.

Gebeurtenisschema's beschrijven de eigenschappen van een gebeurtenis. Een gebeurtenisschema bevat de naam van een gebeurtenisbron en de geordende set eigenschappen voor de gebeurtenis. Verschillende gebeurtenissen kunnen verschillende schema's hebben of hetzelfde schema delen.

Scalaire expressies

Scalaire expressies produceren scalaire waarden. Scalaire expressies zijn onderverdeeld in de volgende soorten:

• Constante expressies
• Verwijzingsexpressies voor eigenschappen
• Expressies voor vergelijken
• Rekenkundige expressies
• Tekenreeksexpressies predicaat

Constante expressies

U vertegenwoordigt constante expressies met behulp van de volgende letterlijke waarden voor elk van de primitieve typen:

Primitief type	JSON-weergave	JSON-voorbeeld	Notities
Bool	Als een JSON Booleaans type	true, false
Datum/tijd	Als een genest object met één eigenschap dateTime in ISO 8601-indelingyyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK.	{"dateTime":"2016-08-01T00:00:00.000Z"}
Dubbele	Een JSON-nummer dat naar het dubbele bereik wordt overgoten.	1.23e45, 123	Dubbele overloop genereert een fout.
Tekenreeks	Een JSON-tekenreekstype	"abc"
Tijdspanne	Als een genest object met één timeSpan-eigenschap in ISO 8601-indeling : P[n]Y[n]M[n]DT[n]H[n]M[n]S.	{"timeSpan":"P1Y2M3DT4M5.67S"}

Primitieve typen die null kunnen worden gebruikt

Primitieve gegevenstypen kunnen op null worden uitgevoerd. null waarden voor primitieve typen worden als volgt uitgedrukt in JSON:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Verwijzingsexpressies voor eigenschappen

U gebruikt een verwijzingsexpressie voor eigenschappen om toegang te krijgen tot de waarden van niet-ingebouwde eigenschappen van een gebeurtenis. Niet-ingebouwde eigenschappen omvatten elke aangepaste eigenschap naast de standaardeigenschappen die automatisch zijn opgenomen in een gebeurtenisschema.

Het resultaattype van een eigenschapsreferentieexpressie is het primitieve type van de eigenschap. Eigenschappen in het gebeurtenisschema worden uniek geïdentificeerd door naam en type, en voor de verwijzingsexpressie moeten beide worden opgegeven.

• JSON-voorbeelden:

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

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

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

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

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

Een ingebouwde verwijzingsexpressie voor eigenschappen wordt gebruikt om toegang te krijgen tot ingebouwde eigenschappen van een gebeurtenis. Ingebouwde eigenschappen zijn alleen de eigenschappen die automatisch worden gedefinieerd in een gebeurtenisschema.

Het resultaattype van een ingebouwde eigenschapsverwijzingsexpressie is het primitieve type van de eigenschap. Naar ingebouwde eigenschappen wordt alleen op naam verwezen; Daarom is er geen type nodig in de verwijzingsexpressie:

{ "builtInProperty": "$esn" }

Expressies voor vergelijken

De volgende Booleaanse vergelijkingsexpressies worden ondersteund:

Eigenschapsnaam in JSON	Beschrijving
eq	Is gelijk aan
Inch	In (gelijk aan alle)
Zin	Bevat woordgroep
startsWith	Begint met
endsWith	Eindigt met woordgroep
Regex	Komt overeen met reguliere expressie
lt	Kleiner dan
Lte	Kleiner dan of gelijk aan
gt	Groter dan
Gte	Groter dan of gelijk aan

Belangrijk

• Alle vergelijkingsexpressies gebruiken de primitieve typen linker- en rechterargumenten en retourneren een Booleaanse waarde die het resultaat van de vergelijking vertegenwoordigt.
• Beide typen argumenten links en rechts in vergelijkingen moeten overeenkomen.
• Alle typen worden impliciet alleen naar zichzelf gecast en expliciete casts worden niet ondersteund.

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

• JSON-voorbeelden:

  {
     "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"
     }
  }
  

De volgende tabel bevat ondersteunde typen argumenten voor elk van de vergelijkingsexpressies:

Argumenttype	Ondersteunde vergelijkingsbewerking
Bool	eq, in
Datum/tijd	eq, in, lt, lte, gt, gte
Dubbele	eq, in, lt, lte, gt, gte
Tekenreeks	eq, in, phrase, startsWith, endsWith, regex
Tijdspanne	eq, in, lt, lte, gt, gte

De null-letterlijke waarde kan alleen worden gebruikt met de volgende vergelijkingsoperatoren: eq of in.

• De operator eq resulteert in true als beide zijden waarden zijn null . Anders resulteert de operator in false.
• Voor andere bewerkingen wordt de fout gegenereerd voor de letterlijke null-waarde en is het gedrag niet gedefinieerd voor null-waarde-eigenschappen (elke vergelijkingsbewerking die resulteert in false).
• Een null waarde gaat vooraf aan niet-null-waarden in sorteervolgordes (bijvoorbeeld als sorteren op een eigenschap wordt toegepast om een lijst met gebeurtenissen te retourneren).

Azure Time Series Insights Gen1 ondersteunt de volgende logische booleaanse expressies:

Eigenschapsnaam in JSON	Beschrijving
and	Neemt een niet-lege set Booleaanse argumenten en retourneert true als ze allemaal resulteren in true.
or	Neemt een niet-lege set Booleaanse argumenten en retourneert true als een van deze argumenten resulteert in true.
Niet	Neemt één Booleaans argument en retourneert de ontkende waarde.

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

De eigenschap stringComparison is optioneel. De standaardwaarde is OrdinalIgnoreCase, waardoor zinsbevating wordt genegeerd in vergelijkingen.

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

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

Rekenkundige expressies

Azure Time Series Insights Gen1 ondersteunt de volgende rekenkundige expressies:

Eigenschapsnaam in JSON	Beschrijving
add	Optellen
sub	Aftrekking
Mult	Vermenigvuldigen
div	Afdeling

Alle rekenkundige expressies nemen de linker- en rechterargumenten van primitieve typen en retourneren een waarde die het resultaat van de bewerking vertegenwoordigt.

Alle typen worden impliciet alleen naar zichzelf gecast en expliciete casts worden niet ondersteund.

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

In de volgende tabel ziet u ondersteunde typen argumenten voor elk van de rekenkundige expressies:

Bewerking	Type links	Rechtertype	Resultaattype
add	Dubbele	Dubbele	Dubbele
add	Tijdspanne	Tijdspanne	Tijdspanne
add	Datum/tijd	Tijdspanne	Datum/tijd
add	Tijdspanne	Datum/tijd	Datum/tijd
sub	Dubbele	Dubbele	Dubbele
sub	Tijdspanne	Tijdspanne	Tijdspanne
sub	Datum/tijd	Datum/tijd	Tijdspanne
sub	Datum/tijd	Tijdspanne	Datum/tijd
Mul	Dubbele	Dubbele	Dubbele
div	Dubbele	Dubbele	Dubbele

Tekenreeksexpressies predicaat

Booleaanse predicaattekenreeksexpressies bevatten Booleaanse predicaten die worden weergegeven als door mensen leesbare expressies, predicaattekenreeksen genoemd.

Voorbeelden van predicaattekenreeksen:

Predicaattekenreeks	Beschrijving
Description HAS 'hello world'	true voor gebeurtenissen die de woordgroep hello world in de eigenschap Beschrijving in alle gebeurtenisbronnen bevatten
'hello world'	true voor gebeurtenissen die de woordgroep bevatten hello world
startsWith(Status, 'go')	true voor gebeurtenissen met status die beginnen met go
endsWith(Status, 'oD')	true voor gebeurtenissen met status die eindigen op od
startsWith_cs(Status, 'Go')	true voor gebeurtenissen met status die beginnen met Go
endsWith_cs(Status, 'od')	true voor gebeurtenissen met status die beginnen met od
matchesRegex(s, '^G*')	true voor gebeurtenissen met de status die overeenkomt met de reguliere expressie ^G*
PointValue.Double = 3.14	true voor gebeurtenissen met dubbele puntwaarde gelijk aan 3.14
Status IN ('Good','Bad')	truevoor gebeurtenissen met Status die of bevat GoodBad
PointValue > 3.14 AND Status.String = 'Good'	true voor gebeurtenissen met puntwaarde groter dan 3.14 en tekenreeksstatus van Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'	true voor gebeurtenissen met puntwaarde groter dan 3.14 en Status van Good of Bad en Beschrijving die de woordgroep niet bevatten hello world

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

De expressie in de predicaattekenreeks wordt geëvalueerd als een JSON-booleaanse expressie. Deze moet voldoen aan de volgende (vereenvoudigde) grammatica:

JSON Booleaanse expressie	Backus–Naur-formulier
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 gen1 primitieve gegevenstypen worden ondersteund in predicaattekenreeksexpressies.

In tegenstelling tot JSON-eigenschapsreferentieexpressies kan een type voor een eigenschap worden weggelaten, in welk geval automatisch een type wordt afgeleid.

Ondersteunde letterlijke waarden

Primitief type	Literals
Bool	TRUE, FALSE
Datum/tijd	dt'2016-10-08T03:22:55.3031599Z'
Dubbele	1.23, 1.0
Tekenreeks	'abc'
Tijdspanne	ts'P1Y2M3DT4M5.67S'
	NULL

Ondersteunde operandtypen

Bewerking	Ondersteunde typen	Notities
<, >, <=, >=	Double, DateTime, TimeSpan
=, !=, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> is gelijk aan !=
+, -, *, /	Double, DateTime, TimeSpan
INCH	String, Bool, Double, DateTime, TimeSpan, NULL	Alle operanden moeten van hetzelfde type zijn of null-constante zijn. Meerdere NULL-szijn gelijk aan één NULL.
HAS	Tekenreeks	Alleen constante letterlijke tekenreeksen zijn toegestaan aan de rechterkant. Lege tekenreeks en NULL zijn niet toegestaan.

Voor vergelijkingspredicaten (<, , >=<, >=, =, !=) en het predicaat IN kan operand NULL zijn of één type hebben.

Voor expressies met een HAS-predicaat kan de constante letterlijke waarde aan de rechterkant van de HAS-operand worden uitgebreid in meerdere typen. Bovendien wordt de constante letterlijk aan de rechterkant van de HAS-operand geparseerd in een Bool-, Double-, DateTime- of TimeSpan-waarde. Voor elke waarde die is geparseerd, wordt een predicaat met de = operator gemaakt. Deze predicaten en het oorspronkelijke HAS-predicaat worden samengevoegd tot een OF-predicaat. Een predicaattekenreeks p1 HAS '1.0' is bijvoorbeeld gelijk aan p1.String HAS '1.0' OR p1.Double = 1.0, als p1-eigenschappen met de typen Tekenreeks en Dubbel bestaan.

Typecontrole

Predicaatexpressies worden gecontroleerd en gevalideerd om ervoor te zorgen dat de typen rechts en links in de expressies overeenkomen.

Belangrijk

• Wanneer de constanten links en rechts van een operand niet overeenkomen, treedt er een fout op.
• Er wordt ook een fout gegenereerd als een bewerking niet is toegestaan op of tussen specifieke typen.

• Als een type is opgegeven voor eigenschap, wordt een typecontrole toegepast:

  • Elk eigenschapstype wordt geaccepteerd op basis van een letterlijke NULL-waarde .

  • Anders moeten de typen links en rechts overeenkomen.

    Voorbeelden van eigenschappen p1 en p2 van het type Tekenreeks en eigenschap p3 van het type Double worden weergegeven in de volgende tabel:

    Predicaattekenreeks	Is geldig?	Notities
    p1.String = 'abc'	Ja
    p1.String = p2.String	Ja
    p1.String = NULL	Ja	NULL komt overeen met elk type aan de linkerkant.
    p3.Double = 'abc'	Nee	Het type komt niet overeen.
    p3.Double = p1.String	Nee	Het type komt niet overeen.
    p1.String HAS 'abc'	Ja
    p3.Double HAS '1.0'	Ja	Letterlijke tekenreeks is geparseerd naar een dubbele waarde.

• Als een type wordt weggelaten voor de eigenschap, maar een naam is opgegeven, worden de volgende stappen uitgevoerd:

  1. Alle eigenschappen met een opgegeven naam en typen worden gebruikt.
  2. Operanden links en rechts zijn gegroepeerd in paren op type.
  3. Paren worden samengevoegd met behulp van AND-bewerkingen .

  • Voorbeelden van eigenschappen p1 en p2 van de typen Tekenreeks en Dubbel en enkele van hun equivalenten worden weergegeven in de volgende tabel:

    Predicaattekenreeks	Equivalent sterk getypeerde predicaattekenreeks	Notities
    p1 = 'abc'	p1.String = 'abc'
    p1 = true		Geen p1-eigenschap van het type Bool, dus er wordt een fout met een ontbrekende eigenschap gegenereerd.
    p1 = NULL	p1.String = NULL AND p1.Double = NULL	Aan NULL de rechterkant wordt ervan uitgegaan dat alle overeenkomende eigenschappen moeten zijn NULL.
    p1 != NULL	p1.String != NULL OR p1.Double != NULL	Dit is een omkering van de voorgaande expressie.
    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	Dit is het equivalent van p1 = NULL.
    p1 HAS '1.0'	p1.String HAS '1.0' OR p1.Double = 1.0	De letterlijke tekenreeks is geparseerd tot een geldige dubbele waarde.
    p1 HAS 'true'	p1.String HAS 'true'	De letterlijke tekenreeks is geparseerd naar Bool, maar geen p1. Bool-eigenschap bestaat.
    p1 = p2	p1.String = p2.String AND p1.Double = p2.Double
    p1 != p2	p1.String != p2.String OR p1.Double != p2.Double	Dit is een omkering van de voorgaande expressie.

• Zowel de eigenschapsnaam als het type kunnen worden weggelaten voor een eigenschap aan de linkerkant als het eigenschapstype aan de rechterkant goed is gedefinieerd. Dit geldt wanneer de rechterkant constante letterlijke waarden heeft en deze niet alleen een NULL letterlijke waarde bevat.

  • Dit scenario is een generalisatie van zoeken in volledige tekst die gebruikmaakt van de HAS-operand.

  • Alle eigenschappen die overeenkomen met het type rechts worden overgenomen en de resulterende expressies worden samengevoegd via een OF-bewerking .

  • Voorbeelden van eigenschap p1 van de typen Tekenreeks en Dubbel en eigenschap p2 van de typen Tekenreeks en Datum/ tijd worden weergegeven in de volgende tabel:

    Predicaattekenreeks	Equivalente, sterk getypeerde predicaattekenreeks	Notities
    = 'abc'	p1.String = 'abc' OR p2.String = 'abc'
    != 'abc'	p1.String != 'abc' AND p2.String != 'abc'	Inversie van de voorgaande expressie
    = 1.0	p1.Double = 1.0
    = dt'2000-01-02T03:04:05'	p2.DateTime = dt'2000-01-02T03:04:05'
    = true		Fout. Er bestaat geen bool-eigenschap , dus er wordt een fout met een ontbrekende eigenschap gegenereerd.
    = NULL		Fout. Het is niet toegestaan om de naam van de eigenschap aan NULL de rechterkant weg te laten.
    IN (NULL)		Hetzelfde als de voorgaande fout.
    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'	Er is geen eigenschap met het type Bool.

• Als de operator samen met een eigenschapsnaam wordt weggelaten, wordt uitgegaan van de HAS bewerking.

Scalaire functies

Scalaire functies retourneren scalaire waarden.

Systeemeigen functies

Scalaire functies die out-of-box worden ondersteund door Azure Time Series Insights Gen1 zijn onder andere:

Functienaam	Retourwaarde	Argumenten	Voorbeeld	Opmerkingen
utcNow	Datum/tijd	Geen	utcNow()	Retourneert de huidige tijd in UTC-indeling. De functienaam is hoofdlettergevoelig.

De functie UTC nu retourneert een Datum/ tijd-waarde, die de huidige tijd in UTC-indeling bevat. Er worden geen argumenten geaccepteerd.

Samenvoegingsexpressies

Aggregatie-expressies worden gebruikt voor het partitioneren van verzamelingen van gebeurtenissen en rekenmetingen over de partities. Aggregatie-expressies zijn onderverdeeld in de volgende soorten:

• Dimensie-expressies
• Expressies voor unieke waarden
• Datum histogramexpressies
• Expressies voor metingen

Dimensie-expressies

U gebruikt dimensie-expressies in een aggregatiecomponent om een set gebeurtenissen te partitioneren en een scalaire sleutel toe te wijzen aan elke partitie.

Dimensieexpressietypen:

Eigenschapsnaam in JSON	Beschrijving	Voorbeeld
Uniquevalues	Dimensiewaarden in het resultaat zijn exacte waarden van een bepaalde eigenschap.
dateHistogram	Dimensiewaarden in het resultaat zijn tijdsbereiken van een bepaalde eigenschap.	Het datum histogram van de tijdstempel kan resulteren in 10 bereiken van 1 uur voor een zoektijdsspanne van 10 uur.
numericHistogram	Dimensiewaarden in het resultaat zijn waardenbereiken in een bepaalde eigenschap.	Het numerieke histogram van de temperatuur kan resulteren in een retournering van 10 gradenbereiken.

Azure Time Series Insights Gen1 beperkt de maximale kardinaliteit of maximale rastergrootte van een geaggregeerde invoerquery tot 150.000 cellen. Als u de kardinaliteit van een statistische query wilt berekenen, vermenigvuldigt u de grootte van alle dimensies in de query. Zolang het product kleiner is dan 150.000, wordt de query geaccepteerd voor uitvoering. Als het product gelijk is aan of kleiner is dan 150.000, wordt de query geweigerd.

U geeft de maximale grootte op van een dimensie die wordt geproduceerd door uniqueValues en numericHistogram met behulp van de take-component . In dateHistogram wordt de grootte berekend door het zoekbereik te delen door de grootte van het dateHistogram-interval , dat u opgeeft met behulp van de component breaks .

Voor een statistische query is bijvoorbeeld het zoekbereik ingesteld van '2017-11-15T16:00:00.000Z' tot '2017-11-15T19:00:00.000Z' = 3 uur. Als de query dateHistogram met de component breaks bevat, ingesteld op 1 minuut (dimensie 1) en uniqueValues over eigenschap XYZ, is de dimensiegrootte dateHistogram 3x60=180. Dit resultaat betekent dat uniqueValues maximaal 150.000/180 = 833 items in totaal kunnen duren.

Expressies voor unieke waarden

U gebruikt een unieke waardenexpressie om een set gebeurtenissen te groeperen op de waarden van een opgegeven gebeurteniseigenschap.

Evaluatie van deze JSON-expressie resulteert in maximaal 100 records, die zijn gegroepeerd op de sensorId eigenschap Tekenreeks.

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

Datum histogramexpressies

U gebruikt een datum histogramexpressie om de eigenschapswaarden DateTime te groeperen in buckets van een opgegeven grootte.

Een evaluatie van deze JSON-expressie resulteert in een set tijdstempelrecords die zodanig zijn afgerond dat elke waarde seconden nul heeft.

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

Expressies voor numerieke histogrammen

U gebruikt een numerieke histogramexpressie om dubbele eigenschapswaarden te groeperen in een opgegeven aantal buckets.

Een evaluatie van deze JSON-expressie resulteert in 10 records, dus het bereik tussen de minimum- en maximumwaarden van de eigenschap p1 is verdeeld in 10 buckets.

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

Expressies voor metingen

U gebruikt metingexpressies in aggregatiecomponenten om een scalaire waarde te berekenen op een set gebeurtenissen. Een metingexpressie is bijvoorbeeld de berekening van de maximumwaarde die is gemeten door een temperatuursensor in de afgelopen 24 uur.

U gebruikt een count-expressie om het aantal gebeurtenissen binnen een bijbehorende bucket te berekenen.

{ "count": {} }

U gebruikt expressies min, max, avg en som om het minimum, maximum, gemiddelde van en som van de waarden voor een opgegeven eigenschap in een bijbehorende bucket te berekenen.

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

Met de expressies voor de eerste en laatste meting kunt u de waarde ophalen van een opgegeven eigenschap A die overeenkomt met de minimum- of maximumwaarde van eigenschap B.

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

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

De component orderBy is optioneel en wordt standaard ingesteld op de eigenschap Timestamp$ts. De invoer kan van elk type zijn. De orderBy-component ondersteunt alleen de typen Double en DateTime .

Als eigenschap B een datum/tijd-type is, krijgt u de meest recente of de vroegste waarde van eigenschap A.

U kunt de eerste en laatste expressie gebruiken om inzicht te geven in de vroegste of laatste waarde van een specifieke eigenschap. Als u bijvoorbeeld een eigenschap hebt met de naam deviceID en u wilt weten wat de laatste deviceID is die een gebeurtenis heeft verzonden, is last de meest efficiënte expressieoperator die u kunt gebruiken om die informatie te identificeren.

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

Een ander voorbeeld is om laatste te gebruiken om de laatst gerapporteerde locatie van een bepaald object te vinden, zoals een schip, voertuig of ander bewegend object.

Als u een query wilt illustreren die de laatst bekende locatie van de schepen in een vloot produceert, kunt u een query maken die er ongeveer als volgt uitziet:

{
  "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"
            }
          }
        }
      ]
    }
  ]
}

Een ander voorbeeld is om eerst een apparaat te vinden dat de laagste druk voor elke installatie rapporteert:

{
  "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"
            }
          }
        }
      ]
    }
  ]
}

Ondersteuning voor dimensie- en metingstype

Dit zijn de ondersteunde dimensie- en meetexpressies, op basis van het eigenschapstype:

Eigenschapstype	Ondersteunde dimensie-expressies	Ondersteunde metingexpressies
Bool	"uniqueValues"	"first" (invoer), "last" (invoer)
Datum/tijd	"uniqueValues", "dateHistogram"	"min""first" , "max"(orderBy, invoer), "last” (orderBy, invoer)
Dubbele	"uniqueValues", "numericHistogram"	"sum", "avg", "min", "max""first" (orderBy, invoer), "last” (orderBy, invoer)
Tekenreeks	"uniqueValues"	"first" (invoer), "last" (invoer)

Componenten

Componenten vormen samenstellende onderdelen van JSON-query's of een deel van een expressie. Componenten zijn onderverdeeld in de volgende soorten:

• Zoekbereikcomponenten
• Predicaatclausules
• Topcomponenten beperken
• Clausules voor het nemen van limieten
• Voorbeeldclausules beperken
• Componenten met onderbrekingen
• Aggregatie-componenten

Zoekbereikcomponenten

U gebruikt een zoekperiodecomponent om een ingebouwde timestamp-eigenschap van een gebeurtenis te filteren op een bepaald interval. Het begin van het interval is inclusief. Het einde van het interval is exclusief.

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

De eigenschappen van en naar in de zoekbereikcomponent (searchSpan) moeten geldige expressies van het resultaattype DateTime zijn. Deze expressies worden geëvalueerd voordat de query wordt uitgevoerd, wat betekent dat ze geen eigenschapsverwijzingen mogen bevatten.

Predicaatclausules

U gebruikt een predicaatcomponent om gebeurtenissen te filteren die voldoen aan het predicaat. Deze moet worden omgezet in een Booleaanse expressie.

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

Gebeurtenissen filteren betekent dat een predicaat wordt uitgevoerd dat wordt vertegenwoordigd door een Boole-expressie voor elke gebeurtenis in de omgeving. De uitvoering van een expressie op een gebeurtenis retourneert als de gebeurtenis moet worden opgenomen in verdere bewerkingen true . Deze retourneert false als de gebeurtenis uit verdere verwerking moet worden weggelaten.

Notitie

Gebeurtenissen worden altijd gefilterd op zoekbereik, naast filters die zijn opgegeven in een predicaatexpressie.

Topcomponenten beperken

U gebruikt de component *limit top om een opgegeven aantal waarden op te halen in oplopende of aflopende volgorde. Het aantal waarden is beperkt volgens het opgegeven aantal.

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

Clausules voor het nemen van limieten

U kunt een component voor het nemen van limieten gebruiken als een snelle manier om een set waarden in een niet-specifieke volgorde op te halen. Het aantal geretourneerde waarden wordt beperkt door de opgegeven invoer.

{ "take": 10 }

Voorbeeldclausules beperken

U gebruikt een *limit sample component om een statistisch representatieve steekproef op te halen uit een set waarden. Het aantal geretourneerde waarden wordt beperkt door de opgegeven invoer.

{ "sample": 10 }

Componenten met onderbrekingen

U gebruikt een *breaks-component in histogramexpressies om op te geven hoe een bereik moet worden verdeeld.

Voor datum histogrammen moet u de grootte van de datum/tijd-interval- en intervalgrenzen opgeven. U doet dit tenzij het histogram is gebaseerd op een ingebouwde timestamp-eigenschap waarbij de grenzen worden bepaald op basis van het zoekbereik:

• Intervalgrenzen zijn optioneel en kunnen worden gebruikt. U kunt ze bijvoorbeeld gebruiken wanneer ze worden bepaald op basis van een zoekperiode als intervalgrenzen worden weggelaten.
• Voor numerieke histogrammen moet u het aantal einden opgeven. U bepaalt intervalgrenzen op basis van de minimum- en maximumwaarden van een eigenschap.

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

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

Aggregatie-componenten

U gebruikt een aggregatiecomponent om een set gebeurtenissen te partitioneren op basis van een bepaalde eigenschap terwijl u de waarden van andere gebeurteniseigenschappen meet.

Metingen worden geëvalueerd op elke partitie die wordt geproduceerd door de dimensieexpressie.

• In het volgende JSON-voorbeeld worden de gemiddelde, minimum- en maximumtemperaturen per sensor-id berekend.

  {
    "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"
              }
            }
          }
        ]
      }
    ]
  }
  

  Notitie

  Een aggregatiecomponent is een matrix waarmee u meer dan één aggregatie op het hoogste niveau kunt opgeven.

• In het volgende JSON-voorbeeld wordt de gemiddelde temperatuur per plaats en per fabrikant onafhankelijk berekend:

  {
    "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"
              }
            }
          }
        ]
      }
    ]
  }
  

  Notitie

  • Het hebben van meer dan één element in een aggregatiematrix wordt momenteel niet ondersteund.
  • Een aggregatiedefinitie kan echter een geneste matrix bevatten die een flexibeler, multidimensionaal raster aangeeft.

• In het volgende JSON-voorbeeld wordt de gemiddelde temperatuur per sensor-id per minuut berekend.

  {
    "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"
                }
              }
            }
          ]
        }
      }
    ]
  }
  

Zie ook

• Zie Gen1 API's voor meer informatie over de Azure Time Series Insights Gen1-API's.

• Zie Verificatie en autorisatie voor meer informatie over aanvraag- en verificatieparameters.

• Meer informatie over Azure Time Series Insights Gen1 vindt u in de Gen1-documentatie.