Freigeben über

Azure Time Series Insights Gen1-Abfragesyntax

  • Artikel

Achtung

Dies ist ein Artikel zu Azure Time Series Insights Gen1.

In diesem Artikel werden das Abfrageanforderungsformat und die Syntax für die Azure Time Series Insights Gen1-Abfrage-API beschrieben.

Zusammenfassung

Wichtig

  • Abfrageanforderungen müssen im JSON-Format vorliegen.
  • HTTP-Anforderungsnutzlasten, die an die Abfrage-API vorgenommen werden, sollten dem in diesem Artikel angegebenen Format entsprechen.

Die Sprache ist in die folgenden Elemente unterteilt:

Datenmodell

Die Azure Time Series Insights Gen1-Abfrage-API arbeitet mit Daten, die als einzelne Ereignisse in einer Umgebung gespeichert werden. Jedes Ereignis ist ein Satz von Eigenschaftsnamen - und Wertpaaren .

Ereigniseigenschaften

Ereigniseigenschaften können einen der folgenden primitiven Typen aufweisen: Bool, DateTime, Double oder String. Alle primitiven Typen können NULL-Werte zulassen.

Hinweis

Benutzerdefinierte Ereignisquellenformate unterstützen möglicherweise einen größeren Satz von Werttypen. Azure Time Series Insights Gen1 leitet den nächstgelegenen primitiven Typ ab und wandelt dann beim Eingang angepasste Typen in sie um.

Alle Ereignisse verfügen über die folgenden integrierten Eigenschaften mit einem vordefinierten Namen und Typ:

Eigenschaftenname Eigenschaftstyp Definition
$ts DateTime Ereigniszeitstempel
$esn String Name der Ereignisquelle

  • Ereigniszeitstempel

    Standardmäßig wird von der Ereignisquelle ein Ereigniszeitstempelwert bereitgestellt. Beispielsweise würden Ereignisse, die von einem IoT Hub stammen, als Zeitstempel in die Warteschlange eingereiht werden.

    Kunden können dieses Verhalten ändern, indem sie stattdessen eine andere Ereigniseigenschaft konfigurieren. Benutzerdefinierte Zeitstempeleigenschaften können in Event Hubs und IoT Hubs angegeben werden.

  • Name der Ereignisquelle

    Der Name der Ereignisquelle ist der Name, der für die Ereignisquelle angezeigt wird, von der Azure Time Series Insights Gen1 das Ereignis empfangen hat. Ereignisquellennamen werden einem bestimmten Ereignis zur Eingangszeit zugeordnet.

    Wichtig

    • Ereignisquellennamen bleiben für die Lebensdauer des Ereignisses unverändert.
    • Wenn der Name einer Ereignisquelle geändert wird, tragen vorhandene Ereignisse den alten Namen der Ereignisquelle. Neue Ereignisse tragen den namen der neuen Ereignisquelle.

Ereignistypen

Benutzerdefinierte Ereigniseigenschaften werden eindeutig identifiziert und in Abfrageausdrücken anhand von Name und Typ referenziert. Ein Ereignis kann mehrere Eigenschaften mit demselben Namen und unterschiedlichen Typen aufweisen. Eigenschaften mit demselben Namen, aber unterschiedlichen Typen können aus der Aufteilung des Eingangstyps resultieren.

Ein Ereigniseigenschaftswert vom Typ String kann in den folgenden Fällen als Eigenschaft mit einem anderen Typ gespeichert werden:

  • Wenn ein String-Wert ein gültiger Double-Wert ist, wird er sowohl als Double als auch als String gespeichert.
  • Wenn ein String-Wert ein gültiger DateTime-Wert ist, wird er nur als DateTime gespeichert.

Die Abfrage-API konvertiert leere Strings-Literale ("") null in die Ausgabe.

Azure Time Series Insights Gen1 verfügt über eingeschränkte Unterstützung für die folgenden Werte innerhalb des Double-Typs: Double.NaN, Double.PositiveInfinityund Double.NegativeInfinity. Diese Werte werden während des Eingangs in konvertiert null , aber wenn die Abfrageauswertung einen dieser Werte erzeugt, wird der Wert ausgewertet und als Antwort als Zeichenfolge serialisiert.

Sie können diese Werte als Zeichenfolgen für eingehenden Datenverkehr übergeben. Daher sollten diese Werte in Abfrageausdrücken auch als Zeichenfolgen übergeben werden.

Ereignisschemas beschreiben die Eigenschaften eines Ereignisses. Ein Ereignisschema enthält den Namen einer Ereignisquelle und den geordneten Satz von Eigenschaften für das Ereignis. Verschiedene Ereignisse können unterschiedliche Schemas haben oder dasselbe Schema gemeinsam nutzen.

Skalare Ausdrücke

Skalare Ausdrücke erzeugen skalare Werte. Skalare Ausdrücke werden in die folgenden Arten unterteilt:

Konstante Ausdrücke

Sie stellen konstante Ausdrücke dar, indem Sie die folgenden Literale für jeden der primitiven Typen verwenden:

Primitiver Typ JSON-Darstellung JSON-Beispiel Notizen
Bool Als boolescher JSON-Typ true, false
DateTime Als geschachteltes Objekt mit einer einzelnen dateTime-Eigenschaft im ISO 8601-Formatyyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK. {"dateTime":"2016-08-01T00:00:00.000Z"}
Double Eine JSON-Zahl, die in den Double-Bereich umgewandelt wird. 1.23e45, 123 Doppelte Überläufe generieren einen Fehler.
String Ein JSON-Zeichenfolgentyp "abc"
TimeSpan Als geschachteltes Objekt mit einer einzelnen timeSpan-Eigenschaft im ISO 8601-Format : P[n]Y[n]M[n]DT[n]H[n]M[n]S. {"timeSpan":"P1Y2M3DT4M5.67S"}

Nullable primitive Typen

Primitive Datentypen können NULL-Werte zulassen. null Werte für primitive Typen werden wie folgt in JSON ausgedrückt:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Eigenschaftenverweisausdrücke

Sie verwenden einen Eigenschaftenverweisausdruck , um auf die Werte von nicht integrierten Eigenschaften eines Ereignisses zuzugreifen. Nicht integrierte Eigenschaften enthalten alle benutzerdefinierten Eigenschaften, die über die Standardeigenschaften hinausgehen, die automatisch in einem Ereignisschema enthalten sind.

Der Ergebnistyp eines Eigenschaftenverweisausdrucks ist der primitive Typ der Eigenschaft. Eigenschaften im Ereignisschema werden nach Name und Typ eindeutig identifiziert, und für den Verweisausdruck müssen beide angegeben werden.

  • JSON-Beispiele:

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

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

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

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

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

Ein integrierter Eigenschaftenverweisausdruck wird verwendet, um auf integrierte Eigenschaften eines Ereignisses zuzugreifen. Integrierte Eigenschaften sind nur die Eigenschaften, die automatisch in einem Ereignisschema definiert werden.

Der Ergebnistyp eines integrierten Eigenschaftenverweisausdrucks ist der primitive Typ der Eigenschaft. Auf integrierte Eigenschaften wird nur mit dem Namen verwiesen. Daher ist kein Typ im Verweisausdruck erforderlich:

{ "builtInProperty": "$esn" }

Vergleichsausdrücke

Die folgenden booleschen Vergleichsausdrücke werden unterstützt:

Eigenschaftenname in JSON BESCHREIBUNG
eq Gleich
in In (gleich jedem)
phrase Enthält Einen Ausdruck.
startsWith Beginnt mit
endsWith Endet mit dem Ausdruck
regex Entspricht dem regulären Ausdruck
lt Kleiner als
lte Kleiner als oder gleich
gt Größer als
Gte Größer als oder gleich

Wichtig

  • Alle Vergleichsausdrücke verwenden die primitiven Typen von linken und rechten Argumenten und geben einen booleschen Wert zurück, der das Ergebnis des Vergleichs darstellt.
  • Beide Typen der linken und rechten Argumente im Vergleich sollten übereinstimmen.
  • Alle Typen werden implizit nur in sich selbst umgewandelt, und explizite Umwandlungen werden nicht unterstützt.
{
  "eq": {
    "left": {
      "property": "p1",
      "type": "String"
     },
     "right": "abc"
  }
}

  • JSON-Beispiele:

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

In der folgenden Tabelle werden die unterstützten Argumenttypen für die einzelnen Vergleichsausdrücke aufgeführt:

Argumenttyp Unterstützte Vergleichsvorgänge
Bool eq, in
DateTime eq, in, lt, lte, gt, gte
Double eq, in, lt, lte, gt, gte
String eq, in, phrase, startsWith, endsWith, regex
TimeSpan eq, in, lt, lte, gt, gte

Das NULL-Literal kann nur mit den folgenden Vergleichsoperatoren verwendet werden: eq oder in.

  • Der Eq-Operator führt dazu true , dass beide Seiten Werte sind null . Andernfalls führt der Operator zu false.
  • Bei anderen Vorgängen wird der Fehler für das NULL-Literal ausgelöst, und das Verhalten ist für NULL-Wert-Eigenschaften undefiniert (jeder Vergleichsvorgang, der zu falseführt).
  • Ein null -Wert ist in Sortierreihenfolgen vor Werten ungleich NULL (z. B. wenn die Sortierung nach einer Eigenschaft angewendet wird, um eine Liste von Ereignissen zurückzugeben).

Azure Time Series Insights Gen1 unterstützt die folgenden booleschen logischen Ausdrücke:

Eigenschaftenname in JSON BESCHREIBUNG
and Akzeptiert einen nicht leeren Satz boolescher Argumente und gibt zurück true , wenn alle als ausgewertet werden true.
or Verwendet einen nicht leeren Satz boolescher Argumente und gibt zurück true , wenn eines dieser Argumente als ausgewertet wird true.
not Akzeptiert ein einzelnes boolesches Argument und gibt seinen negierten Wert zurück. 
{
  "and": [
    {
      "eq": {
        "left": {
          "property": "p1",
          "type": "String"
        },
        "right": "abc"
      }
    },
    {
      "not": {
        "lt": {
          "left": {
            "property": "p1",
            "type": "Double"
          },
          "right": 1
        }
      }
    }
  ]
}

Die stringComparison-Eigenschaft ist optional. Der Wert ist OrdinalIgnoreCasestandardmäßig , was dazu führt, dass die Groß- und Kleinschreibung von Sätzen in Vergleichen ignoriert wird.

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

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

Arithmetische Ausdrücke

Azure Time Series Insights Gen1 unterstützt die folgenden arithmetischen Ausdrücke:

Eigenschaftenname in JSON BESCHREIBUNG
add Addition
sub Subtraktion
Mult Multiplikation
div Division

Alle arithmetischen Ausdrücke verwenden die linken und rechten Argumente von primitiven Typen und geben einen Wert zurück, der das Ergebnis des Vorgangs darstellt.

Alle Typen werden implizit nur in sich selbst umgewandelt, und explizite Umwandlungen werden nicht unterstützt.

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

In der folgenden Tabelle werden unterstützte Argumenttypen für die einzelnen arithmetischen Ausdrücke aufgeführt:

Vorgang Linker Typ Rechter Typ Ergebnistyp
add Double Double Double
add TimeSpan TimeSpan TimeSpan
add DateTime TimeSpan DateTime
add TimeSpan DateTime DateTime
sub Double Double Double
sub TimeSpan TimeSpan TimeSpan
sub DateTime DateTime TimeSpan
sub DateTime TimeSpan DateTime
mul Double Double Double
div Double Double Double

Prädikatzeichenfolgenausdrücke

Boolesche Prädikatzeichenfolgenausdrücke enthalten boolesche Prädikate, die als lesbare Ausdrücke dargestellt werden, die als Prädikatzeichenfolgen bezeichnet werden.

Beispiele für Prädikatzeichenfolgen:

Prädikatszeichenfolge BESCHREIBUNG
Description HAS 'hello world' true für Ereignisse, die den Ausdruck hello world in der Description-Eigenschaft für alle Ereignisquellen enthalten
'hello world' true für Ereignisse, die den Ausdruck enthalten hello world
startsWith(Status, 'go') true für Ereignisse mit Status ab go
endsWith(Status, 'oD') true für Ereignisse, deren Status mit endet od
startsWith_cs(Status, 'Go') true für Ereignisse mit Status ab Go
endsWith_cs(Status, 'od') true für Ereignisse mit Status ab od
matchesRegex(s, '^G*') true für Ereignisse mit Status , die dem regulären Ausdruck entsprechen ^G*
PointValue.Double = 3.14 true für Ereignisse mit doppeltem PointValue gleich 3.14
Status IN ('Good','Bad') truefür Ereignisse mit Status, die oder enthält GoodBad
PointValue > 3.14 AND Status.String = 'Good' true für Ereignisse mit PointValue größer als und 3.14 Zeichenfolge Status von Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world' true für Ereignisse mit PointValue größer als 3.14 und Status von Good oder Bad und Description , die den Ausdruck nicht enthalten hello world 
{ "predicateString": "PointValue.Double = 3.14" }

Der Ausdruck in der Prädikatzeichenfolge wird in einen booleschen JSON-Ausdruck ausgewertet. Es sollte der folgenden (vereinfachten) Grammatik entsprechen:

JSON Boolean-Ausdruck 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 Primitive Gen1-Datentypen werden in Prädikatzeichenfolgenausdrücken unterstützt.

Im Gegensatz zu JSON-Eigenschaftenverweisausdrücken kann ein Typ für eine Eigenschaft weggelassen werden. In diesem Fall wird automatisch ein Typ abgeleitet.

Unterstützte Literale

Primitiver Typ Literale
Bool TRUE, FALSE
DateTime dt'2016-10-08T03:22:55.3031599Z'
Double 1.23, 1.0
String 'abc'
TimeSpan ts'P1Y2M3DT4M5.67S'
NULL

Unterstützte Operandentypen

Vorgang Unterstützte Typen Notizen
<, >, <, > Double, DateTime, TimeSpan
=, =, <> String, Bool, Double, DateTime, TimeSpan, NULL <> entspricht !=
+, -, *, / Double, DateTime, TimeSpan
IN String, Bool, Double, DateTime, TimeSpan, NULL Alle Operanden müssen denselben Typ aufweisen oder eine NULL-Konstante sein. Mehrere NULLs entsprechen einem einzelnen NULL-Wert.
HAS String Im rechten Bereich sind nur konstante Zeichenfolgenliterale zulässig. Leere Zeichenfolge und NULL sind nicht zulässig.

Für Vergleichsprädikate (<, >, =<,>= , , !=) und das IN-Prädikat operand kann NULL sein oder einen einzelnen Typ aufweisen.

Bei Ausdrücken mit einem HAS-Prädikat kann das konstante Literal auf der rechten Seite des HAS-Operanden in mehrere Typen erweitert werden. Darüber hinaus wird das konstante Literal auf der rechten Seite des HAS-Operanden in einen Bool-, Double-, DateTime- oder TimeSpan-Wert analysiert. Für jeden erfolgreich analysierten Wert wird ein Prädikat mit dem = Operator erstellt. Diese Prädikate und das ursprüngliche HAS-Prädikat werden in ein OR-Prädikat eingebunden. Beispielsweise ist eine Prädikatzeichenfolge p1 HAS '1.0' gleichbedeutend mit p1.String HAS '1.0' OR p1.Double = 1.0, wenn p1-Eigenschaften mit den Typen String und Double vorhanden sind.

Typüberprüfung

Prädikatausdrücke werden typgeprüft und überprüft, um sicherzustellen, dass der rechte und der linke Typ darin übereinstimmen.

Wichtig

  • Wenn die Konstanten links und rechts eines Operanden nicht übereinstimmen, wird ein Fehler ausgelöst.
  • Ein Fehler wird auch ausgelöst, wenn ein Vorgang für oder zwischen bestimmten Typen nicht zulässig ist.

  • Wenn ein Typ für die Eigenschaft angegeben wird, wird eine Typprüfung angewendet:

    • Jeder Eigenschaftstyp wird für ein NULL-Literal akzeptiert.

    • Andernfalls sollten linksseitige und rechte Seitentypen übereinstimmen.

      Beispiele für die Eigenschaften p1 und p2 des String-Typs sowie die Eigenschaft p3 des Double-Typs werden in der folgenden Tabelle angezeigt:

      Prädikatszeichenfolge Ist gültig? Notizen
      p1.String = 'abc' Ja
      p1.String = p2.String Ja
      p1.String = NULL Ja NULL entspricht jedem linken Seitentyp.
      p3.Double = 'abc' Nein Typenkonflikt.
      p3.Double = p1.String Nein Typenkonflikt.
      p1.String HAS 'abc' Ja
      p3.Double HAS '1.0' Ja Zeichenfolgenliteral wurde erfolgreich in einen Double-Wert analysiert.

  • Wenn ein Typ für die Eigenschaft nicht angegeben wird, aber ein Name angegeben wird, werden die folgenden Schritte ausgeführt:

    1. Alle Eigenschaften mit einem angegebenen Namen und Typen werden übernommen.
    2. Operanden auf der linken Seite und rechts sind nach Typ paarweise gruppiert.
    3. Paare werden mithilfe von AND-Vorgängen verkettet.

    • Beispiele für die Eigenschaften p1 und p2 der Typen String und Double sowie einige ihrer Entsprechungen werden in der folgenden Tabelle angezeigt:

      Prädikatszeichenfolge Entsprechende stark typisierte Prädikatzeichenfolge Notizen
      p1 = 'abc' p1.String = 'abc'
      p1 = true Keine p1-Eigenschaft vom Typ Bool, sodass ein fehlender Eigenschaftsfehler ausgegeben wird.
      p1 = NULL p1.String = NULL AND p1.Double = NULL Für NULL die rechte Seite wird davon ausgegangen, dass alle übereinstimmenden Eigenschaften sein NULLsollten.
      p1 != NULL p1.String != NULL OR p1.Double != NULL Dies ist eine Inversion des vorherigen Ausdrucks.
      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 Dies ist das Äquivalent zu p1 = NULL.
      p1 HAS '1.0' p1.String HAS '1.0' OR p1.Double = 1.0 Das Zeichenfolgenliteral wurde erfolgreich auf einen gültigen Double-Wert analysiert.
      p1 HAS 'true' p1.String HAS 'true' Das Zeichenfolgenliteral wurde erfolgreich in Bool analysiert, aber kein p1. Die Bool-Eigenschaft ist vorhanden.
      p1 = p2 p1.String = p2.String AND p1.Double = p2.Double
      p1 != p2 p1.String != p2.String OR p1.Double != p2.Double Dies ist eine Inversion des vorherigen Ausdrucks.

  • Sowohl der Eigenschaftenname als auch der -Typ können für eine linksseitige Eigenschaft weggelassen werden, wenn der rechtsseitige Eigenschaftentyp klar definiert ist. Dies gilt immer dann, wenn die rechte Seite konstante Literale aufweist und nicht nur ein NULL Literal enthält.

    • Dieses Szenario ist eine Generalisierung der Volltextsuche, die den HAS-Operanden verwendet.

    • Alle Eigenschaften, die dem rechtsseitigen Typ entsprechen, werden übernommen, und die resultierenden Ausdrücke werden über einen OR-Vorgang verkettet.

    • Beispiele für die Eigenschaft p1 des String - und Double-Typs sowie der Eigenschaft p2 der String - und DateTime-Typen werden in der folgenden Tabelle angezeigt:

      Prädikatszeichenfolge Entsprechende stark typisierte Prädikatzeichenfolge Notizen
      = 'abc' p1.String = 'abc' OR p2.String = 'abc'
      != 'abc' p1.String != 'abc' AND p2.String != 'abc' Inversion des vorherigen Ausdrucks
      = 1.0 p1.Double = 1.0
      = dt'2000-01-02T03:04:05' p2.DateTime = dt'2000-01-02T03:04:05'
      = true Fehler. Es ist keine Bool-Eigenschaft vorhanden, sodass ein Fehlender Eigenschaftsfehler ausgegeben wird.
      = NULL Fehler. Das Weglassen des Eigenschaftennamens für NULL die rechte Seite ist nicht zulässig.
      IN (NULL) Identisch mit dem vorherigen Fehler.
      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' Es gibt keine Eigenschaft vom Typ Bool.

  • Wenn der Operator zusammen mit einem Eigenschaftennamen ausgelassen wird, wird der HAS Vorgang angenommen.

Skalarfunktionen

Skalare Funktionen geben skalare Werte zurück.

Native Funktionen

Zu den skalaren Funktionen, die von Azure Time Series Insights Gen1 sofort unterstützt werden, gehören:

Funktionsname Rückgabewert Argumente Beispiel Notizen
utcNow DateTime Keine utcNow() Gibt die aktuelle Uhrzeit im UTC-Format zurück. Beim Funktionsnamen wird die Groß-/Kleinschreibung beachtet.

Die UTC now-Funktion gibt einen DateTime-Wert zurück, der die aktuelle Uhrzeit im UTC-Format enthält. Es akzeptiert keine Argumente.

Aggregatausdrücke

Aggregatausdrücke werden verwendet, um Auflistungen von Ereignissen zu partitionieren und Measures über die Partitionen zu berechnen. Aggregatausdrücke sind in die folgenden Arten unterteilt:

Dimensionsausdrücke

Sie verwenden Dimensionsausdrücke innerhalb einer Aggregatklausel , um eine Gruppe von Ereignissen zu partitionieren und jeder Partition einen skalaren Schlüssel zuzuweisen.

Dimensionsausdrucktypen:

Eigenschaftenname in JSON BESCHREIBUNG Beispiel
Uniquevalues Dimensionswerte im Ergebnis sind exakte Werte einer bestimmten Eigenschaft.
dateHistogram Dimensionswerte im Ergebnis sind Zeitbereiche einer bestimmten Eigenschaft. Das Datumshistogramm des Zeitstempels kann für eine Suchdauer von 10 Stunden zu einem Bereich von 10 Stunden führen.
numericHistogram Dimensionswerte im Ergebnis sind Wertebereiche in einer bestimmten Eigenschaft. Das numerische Histogramm der Temperatur kann zu einer Rückgabe von 10 Gradbereichen führen.

Azure Time Series Insights Gen1 beschränkt die maximale Kardinalität oder maximale Gittergröße einer Eingabeaggregatabfrage auf 150.000 Zellen. Um die Kardinalität einer Aggregatabfrage zu berechnen, multiplizieren Sie die Größen aller Dimensionen in der Abfrage. Solange das Produkt kleiner als 150.000 ist, wird die Abfrage für die Ausführung akzeptiert. Wenn das Produkt gleich oder kleiner als 150.000 ist, wird die Abfrage abgelehnt.

Sie geben die maximale Größe einer Dimension an, die von uniqueValues und numericHistogram mithilfe der take-Klausel erzeugt wird. In dateHistogram wird die Größe berechnet, indem die Suchspanne durch die Größe des dateHistogram-Intervalls dividiert wird, das Sie mithilfe der breaks-Klausel angeben.

Bei einer Aggregatabfrage ist beispielsweise die Suchspanne von "2017-11-15T16:00:00.000Z" auf "2017-11-15T19:00:00:00.000Z" = 3 Stunden festgelegt. Wenn die Abfrage dateHistogram mit der breaks-Klausel enthält, die auf 1 Minute (Dimension 1) und uniqueValues über eigenschaft XYZ festgelegt ist, ist die größe der dateHistogram-Dimension 3x60=180. Dies bedeutet, dass uniqueValues bis zu 150.000/180 = 833 Elemente insgesamt in Anspruch nehmen können.

Ausdrücke mit eindeutigen Werten

Sie verwenden einen Ausdruck für eindeutige Werte , um einen Satz von Ereignissen nach den Werten einer angegebenen Ereigniseigenschaft zu gruppieren.

Die Auswertung dieses JSON-Ausdrucks führt zu bis zu 100 Datensätzen, die nach der sensorIdString-Eigenschaft gruppiert werden.

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

Datums histogrammausdrücke

Sie verwenden einen Datumshistogrammausdruck , um DateTime-Eigenschaftswerte in Buckets einer angegebenen Größe zu gruppieren.

Eine Auswertung dieses JSON-Ausdrucks führt zu einer Reihe von Timestamp-Datensätzen , die so gerundet sind, dass für jeden Wert Sekunden nulliert sind.

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

Numerische Histogrammausdrücke

Sie verwenden einen numerischen Histogrammausdruck , um Double-Eigenschaftswerte in einer angegebenen Anzahl von Buckets zu gruppieren.

Eine Auswertung dieses JSON-Ausdrucks führt zu 10 Datensätzen, sodass der Bereich zwischen den Minimal- und Maximalwerten der p1-Eigenschaft in 10 Buckets unterteilt ist.

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

Measureausdrücke

Sie verwenden Measureausdrücke innerhalb von Aggregatklauseln , um einen skalaren Wert für eine Reihe von Ereignissen zu berechnen. Ein Measureausdruck ist beispielsweise die Berechnung des maximalen Werts, der von einem Temperatursensor während der letzten 24 Stunden gemessen wurde.

Sie verwenden einen Count-Ausdruck , um die Anzahl von Ereignissen in einem entsprechenden Bucket zu berechnen.

{ "count": {} }

Sie verwenden min-, max-, avg- und sum-Ausdrücke , um das Minimum, maximum, den Durchschnitt und die Summe der Werte für eine angegebene Eigenschaft in einem entsprechenden Bucket zu berechnen.

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

Mit dem ersten und letzten Measureausdruck können Sie den Wert einer angegebenen Eigenschaft A abrufen, der dem Minimal- oder Maximalwert der Eigenschaft B entspricht.

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

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

Die orderBy-Klausel ist optional und verwendet standardmäßig die Timestamp-Eigenschaft$ts. Die Eingabe kann von einem beliebigen Typ sein. Die orderBy-Klausel unterstützt nur die Typen Double und DateTime .

Wenn Eigenschaft B ein DateTime-Typ ist, erhalten Sie den neuesten oder den frühesten Wert der Eigenschaft A.

Sie können erste und letzte Ausdrücke verwenden, um den frühesten oder neuesten Wert einer bestimmten Eigenschaft zu verstehen. Wenn Sie z. B. eine Eigenschaft namens deviceID haben und die neueste deviceID Nachricht verstehen möchten, die ein Ereignis gesendet hat, ist last der effizienteste Ausdrucksoperator, der zum Identifizieren dieser Informationen verwendet werden kann.

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

Ein anderes Beispiel ist die Verwendung von last , um den zuletzt gemeldeten Standort eines bestimmten Objekts zu finden, z. B. ein Schiff, ein Fahrzeug oder ein anderes sich bewegendes Objekt.

Um eine Abfrage zu veranschaulichen, die den letzten bekannten Standort der Schiffe in einer Flotte erzeugt, können Sie eine Abfrage ähnlich der folgenden erstellen:

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

Ein anderes Beispiel besteht darin, zuerst ein Gerät zu finden, das den niedrigsten Druck für jede Anlage meldet:

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

Unterstützung von Dimensions- und Measuretyp

Hier sind die unterstützten Dimensions- und Measureausdrücke basierend auf dem Eigenschaftentyp:

Eigenschaftstyp Unterstützte Dimensionsausdrücke Unterstützte Measureausdrücke
Bool "uniqueValues" "first" (Eingabe), "last" (Eingabe)
DateTime "uniqueValues", "dateHistogram" "min", "max", "first" (orderBy, input), "last” (orderBy, input)
Double "uniqueValues", "numericHistogram" "sum", "avg", "min""max", , "first" (orderBy, input), "last” (orderBy, input)
String "uniqueValues" "first" (Eingabe), "last" (Eingabe)

Klauseln

Klauseln bilden konstituierende Komponenten von JSON-Abfragen oder einen Teil eines Ausdrucks. Klauseln sind in folgende Arten unterteilt:

Suchspanneklauseln

Sie verwenden eine Suchspanneklausel , um eine integrierte Timestamp-Eigenschaft eines Ereignisses auf ein bestimmtes Intervall zu filtern. Der Anfang des Intervalls ist inklusive. Das Ende des Intervalls ist exklusiv.

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

Die Eigenschaften from und to in der search span-Klausel (searchSpan) sollten gültige Ausdrücke des DateTime-Ergebnistyps sein. Diese Ausdrücke werden vor der Abfrageausführung ausgewertet, was bedeutet, dass sie keine Eigenschaftsverweise enthalten sollten.

Prädikatklauseln

Sie verwenden eine Prädikatklausel , um Ereignisse zu filtern, die das Prädikat erfüllen. Sie sollte in einen booleschen Ausdruck aufgelöst werden.

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

Das Filtern von Ereignissen bedeutet, ein Prädikat auszuführen, das durch einen booleschen Ausdruck für jedes Ereignis in der Umgebung dargestellt wird. Die Ausführung eines Ausdrucks für ein Ereignis gibt zurück true , wenn das Ereignis in weitere Vorgänge einbezogen werden muss. Es wird zurückgegeben false , wenn das Ereignis bei der weiteren Verarbeitung ausgelassen werden muss.

Hinweis

Ereignisse werden immer nach Suchspanne gefiltert, zusätzlich zu allen Filtern, die in einem Prädikatausdruck angegeben sind.

Einschränken der obersten Klauseln

Sie verwenden eine *limit top-Klausel , um eine angegebene Anzahl von Werten in aufsteigender oder absteigender Reihenfolge abzurufen. Die Anzahl der Werte ist gemäß der angegebenen Anzahl begrenzt.

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

Limit take-Klauseln

Sie können eine limit take-Klausel als schnelle Möglichkeit verwenden, um einen Satz von Werten in keiner bestimmten Reihenfolge abzurufen. Die Anzahl der zurückgegebenen Werte wird durch die angegebene Eingabe begrenzt.

{ "take": 10 }

Einschränken von Beispielklauseln

Sie verwenden eine *limit sample-Klausel , um eine statistisch repräsentative Stichprobe aus einem Satz von Werten abzurufen. Die Anzahl der zurückgegebenen Werte wird durch die angegebene Eingabe begrenzt.

{ "sample": 10 }

Breaks-Klauseln

Sie verwenden eine *breaks-Klausel in Histogrammausdrücken, um anzugeben, wie ein Bereich geteilt werden soll.

Für Datumshistogramme sollten Sie die Größe des datetime-Intervalls und der Intervallgrenzen angeben. Sie tun dies, es sei denn, das Histogramm basiert auf einer integrierten Timestamp-Eigenschaft , bei der die Grenzen basierend auf der Suchspanne bestimmt werden:

  • Intervallgrenzen sind optional und können verwendet werden. Sie können sie beispielsweise verwenden, wenn sie basierend auf einer Suchspanne bestimmt werden, wenn Intervallgrenzen weggelassen werden.
  • Für numerische Histogramme sollten Sie die Anzahl der Unterbrechungen angeben. Sie bestimmen Intervallgrenzen basierend auf den minimalen und maximalen Werten einer Eigenschaft.
{
  "breaks": {
    "size": "1d",
    "from": "2000-01-02T03:04:05.0000000",
    "to": "2000-01-02T03:04:05.0000000"
  }
}

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

Aggregates-Klauseln

Sie verwenden eine aggregates-Klausel , um eine Reihe von Ereignissen durch eine bestimmte Eigenschaft zu partitionieren, während Sie die Werte anderer Ereigniseigenschaften messen.

Measures werden für jede Partition ausgewertet, die vom Dimensionsausdruck erzeugt wird.

  • Im folgenden JSON-Beispiel werden die durchschnitts-, minimalen und maximalen Temperaturen pro Sensor-ID berechnet.

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

    Hinweis

    Eine aggregates-Klausel ist ein Array, mit dem Sie mehr als eine Aggregation auf der obersten Ebene angeben können.

  • Im folgenden JSON-Beispiel wird die durchschnittliche Temperatur pro Stadt und Hersteller unabhängig berechnet:

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

    Hinweis

    • Mehrere Elemente in einem Aggregatarray werden derzeit nicht unterstützt.
    • Eine Aggregationsdefinition kann jedoch ein geschachteltes Array enthalten, das ein flexibleres, mehrdimensionales Gitter angibt.

  • Im folgenden JSON-Beispiel wird die durchschnittliche Temperatur pro Sensor-ID pro Minute berechnet.

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

Weitere Informationen