Udostępnij za pośrednictwem

składnia zapytań Azure Time Series Insights Gen1

  • Artykuł

Przestroga

Jest to artykuł z generacji 1.

W tym artykule opisano format żądania zapytania i składnię interfejsu API zapytań Azure Time Series Insights Gen1.

Podsumowanie

Ważne

  • Żądania zapytań muszą mieć format JSON.
  • Ładunki żądań HTTP wykonane w interfejsie API zapytań powinny być zgodne z formatem określonym w tym artykule.

Język jest podzielony na następujące elementy:

Model danych

Interfejs API zapytań Azure Time Series Insights Gen1 działa na danych przechowywanych jako pojedyncze zdarzenia w środowisku. Każde zdarzenie jest zestawem par nazw właściwości i wartości .

Właściwości zdarzenia

Właściwości zdarzenia mogą być jednym z następujących typów pierwotnych: Bool, DateTime, Double lub String. Wszystkie typy pierwotne są dopuszczane do wartości null.

Uwaga

Niestandardowe formaty źródeł zdarzeń mogą obsługiwać większy zestaw typów wartości. Azure Time Series Insights Gen1 wnioskuje najbliższy typ pierwotny, a następnie rzutuje dostosowane typy na ich ruch przychodzący.

Wszystkie zdarzenia mają następujące wbudowane właściwości ze wstępnie zdefiniowaną nazwą i typem:

Nazwa właściwości Typ właściwości Definicja
$ts Data/godzina Sygnatura czasowa zdarzenia
$esn Ciąg Nazwa źródła zdarzeń

  • Sygnatura czasowa zdarzenia

    Domyślnie wartość znacznika czasu zdarzenia jest dostarczana przez źródło zdarzeń. Na przykład zdarzenia pochodzące z centrum IoT będą miały czas w kolejce jako sygnaturę czasową.

    Klienci mogą modyfikować to zachowanie, konfigurując zamiast tego inną właściwość zdarzenia. Niestandardowe właściwości sygnatury czasowej można określić w centrach zdarzeń i centrach IoT.

  • Nazwa źródła zdarzeń

    Nazwa źródła zdarzeń to nazwa wyświetlana dla źródła zdarzeń, z którego Azure Time Series Insights Gen1 odebrało zdarzenie. Nazwy źródeł zdarzeń są skojarzone z określonym zdarzeniem w czasie ruchu przychodzącego.

    Ważne

    • Nazwy źródeł zdarzeń pozostają niezmienione przez okres istnienia zdarzenia.
    • Jeśli nazwa źródła zdarzeń zostanie zmodyfikowana, istniejące zdarzenia przenoszą starą nazwę źródła zdarzeń. Nowe zdarzenia będą miały nową nazwę źródła zdarzeń.

Typy zdarzeń

Niestandardowe właściwości zdarzenia są jednoznacznie identyfikowane i przywoływane w wyrażeniach zapytań według nazwy i typu. Zdarzenie może mieć więcej niż jedną właściwość o tej samej nazwie i różnych typach. Właściwości o tej samej nazwie, ale różne typy mogą wynikać z podziału typu ruchu przychodzącego.

Wartość właściwości zdarzenia typu Ciąg może być przechowywana jako właściwość o innym typie w następujących przypadkach:

  • Jeśli wartość typu Ciąg jest prawidłową wartością podwójną , jest przechowywana zarówno jako Wartość podwójna , jak i Ciąg.
  • Jeśli wartość ciągu jest prawidłową wartością typu Data/godzina , jest przechowywana tylko jako data/godzina .

Interfejs API zapytań konwertuje puste literały ciągów ("") na null w danych wyjściowych.

Azure Time Series Insights Gen1 ma ograniczoną obsługę następujących wartości w ramach typu Podwójne: Double.NaN, Double.PositiveInfinityi Double.NegativeInfinity. Te wartości są konwertowane na null podczas ruchu przychodzącego, ale jeśli ocena zapytania generuje jedną z tych wartości, wartość jest obliczana i serializowana jako ciąg w odpowiedzi.

Te wartości można przekazać jako ciągi dla ruchu przychodzącego, więc w wyrażeniach zapytania te wartości powinny być również przekazywane jako ciągi.

Schematy zdarzeń opisują właściwości zdarzenia. Schemat zdarzenia zawiera nazwę źródła zdarzeń i uporządkowany zestaw właściwości zdarzenia. Różne zdarzenia mogą mieć różne schematy lub współużytkować ten sam schemat.

Wyrażenia skalarne

Wyrażenia skalarne generują wartości skalarne. Wyrażenia skalarne są podzielone na następujące rodzaje:

Wyrażenia stałe

Wyrażenia stałe są reprezentowane przy użyciu następujących literałów dla każdego z typów pierwotnych:

Typ pierwotny Reprezentacja JSON Przykład kodu JSON Uwagi
Bool Jako typ logiczny JSON true, false
Data/godzina Jako obiekt zagnieżdżony z pojedynczą właściwością dateTime w formacie yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFKISO 8601 . {"dateTime":"2016-08-01T00:00:00.000Z"}
Double Liczba JSON rzutowana na podwójny zakres. 1.23e45, 123 Podwójne przepełnienia spowodują wygenerowanie błędu.
Ciąg Typ ciągu JSON "abc"
przedział_czasu Jako obiekt zagnieżdżony z właściwością timeSpan w formacie ISO 8601 : P[n]Y[n]M[n]DT[n]H[n]M[n]S. {"timeSpan":"P1Y2M3DT4M5.67S"}

Typy pierwotne dopuszczane do wartości null

Typy danych pierwotnych są dopuszczane do wartości null. null wartości typów pierwotnych są wyrażane w formacie JSON w następujący sposób:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Wyrażenia odwołania do właściwości

Aby uzyskać dostęp do wartości wbudowanych właściwości zdarzenia, należy użyć wyrażenia odwołania do właściwości właściwości. Właściwości nieubudowane obejmują dowolną niestandardową właściwość poza domyślnymi, które są automatycznie zawarte w schemacie zdarzeń.

Typ wyniku wyrażenia odwołania do właściwości jest typem pierwotnym właściwości. Właściwości w schemacie zdarzeń są jednoznacznie identyfikowane przez nazwę i typ, a wyrażenie odwołania wymaga określenia obu tych elementów.

  • Przykłady kodu JSON:

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

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

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

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

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

Wbudowane wyrażenie odwołania do właściwości służy do uzyskiwania dostępu do wbudowanych właściwości zdarzenia. Wbudowane właściwości to tylko te właściwości, które są automatycznie definiowane w schemacie zdarzeń.

Typ wyniku wbudowanego wyrażenia odwołania do właściwości jest typem pierwotnym właściwości. Właściwości wbudowane są przywoływana tylko przez nazwę; dlatego w wyrażeniu odwołania nie jest wymagany żaden typ:

{ "builtInProperty": "$esn" }

Wyrażenia porównania

Obsługiwane są następujące wyrażenia porównania logicznego :

Nazwa właściwości w formacie JSON Opis
eq Równe
Cala W (równe dowolne)
Wyrażenie Zawiera frazę
Startswith Rozpoczyna się od
Endswith Kończy się frazą
Regex Pasuje do wyrażenia regularnego
lt Mniejsze niż
Lte Mniejsze niż lub równe
gt Większe niż
Gte Większe niż lub równe

Ważne

  • Wszystkie wyrażenia porównania przyjmują typy pierwotne argumentów po lewej i prawej stronie oraz zwracają wartość logiczną reprezentującą wynik porównania.
  • Oba typy argumentów po lewej i prawej stronie w porównaniach powinny być zgodne.
  • Wszystkie typy niejawnie rzutowane tylko do siebie, a jawne rzutowania nie są obsługiwane.
{
  "eq": {
    "left": {
      "property": "p1",
      "type": "String"
     },
     "right": "abc"
  }
}

  • Przykłady kodu 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"
   }
}

W poniższej tabeli przedstawiono obsługiwane typy argumentów dla każdego z wyrażeń porównania:

Typ argumentu Obsługiwana operacja porównania
Bool eq, in
Data/godzina eq, in, lt, lte, gt, gte
Double eq, in, lt, lte, gt, gte
Ciąg eq, in, fraza, startsWith, endsWith, regex
przedział_czasu eq, in, lt, lte, gt, gte

Literał NULL może być używany tylko z następującymi operatorami porównania: eq lub in.

  • Operator eq powoduje, true że obie strony są null wartościami. W przeciwnym razie operator zwraca wartość false.
  • W przypadku innych operacji błąd jest zgłaszany dla literału NULL , a zachowanie jest niezdefiniowane dla właściwości null-value (każda operacja porównania, która powoduje false).
  • Wartość null poprzedza wartości inne niż null w kolejności sortowania (na przykład w przypadku zastosowania sortowania według właściwości w celu zwrócenia listy zdarzeń).

usługa Azure Time Series Insights Gen1 obsługuje następujące wyrażenia logiczne logiczne:

Nazwa właściwości w formacie JSON Opis
and Przyjmuje niepusty zestaw argumentów logicznych i zwraca wartość true , jeśli wszystkie z nich mają wartość true.
Lub Przyjmuje niepusty zestaw argumentów logicznych i zwraca wartość , jeśli którakolwiek z nich zostanie true obliczona na truewartość .
Nie Przyjmuje pojedynczy argument logiczny i zwraca jego negowaną wartość. 
{
  "and": [
    {
      "eq": {
        "left": {
          "property": "p1",
          "type": "String"
        },
        "right": "abc"
      }
    },
    {
      "not": {
        "lt": {
          "left": {
            "property": "p1",
            "type": "Double"
          },
          "right": 1
        }
      }
    }
  ]
}

Właściwość stringComparison jest opcjonalna. Domyślnie jego wartość to OrdinalIgnoreCase, co powoduje ignorowanie wielkości liter zdań w porównaniach.

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

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

Wyrażenia arytmetyczne

usługa Azure Time Series Insights Gen1 obsługuje następujące wyrażenia arytmetyczne:

Nazwa właściwości w formacie JSON Opis
add Znak dodawania
Sub Odejmowanie
Mult Znak mnożenia
div Dział

Wszystkie wyrażenia arytmetyczne przyjmują lewe i prawe argumenty typów pierwotnych i zwracają wartość reprezentującą wynik operacji.

Wszystkie typy niejawnie rzutowane tylko do siebie, a jawne rzutowania nie są obsługiwane.

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

W poniższej tabeli przedstawiono obsługiwane typy argumentów dla każdego z wyrażeń arytmetycznych:

Operacja Typ po lewej stronie Typ właściwy Typ wyniku
add Double Double Double
add przedział_czasu przedział_czasu przedział_czasu
add Data/godzina przedział_czasu Data/godzina
add przedział_czasu Data/godzina Data/godzina
Sub Double Double Double
Sub przedział_czasu przedział_czasu przedział_czasu
Sub Data/godzina Data/godzina przedział_czasu
Sub Data/godzina przedział_czasu Data/godzina
Mul Double Double Double
div Double Double Double

Wyrażenia ciągu predykatu

Wyrażenia ciągu predykatu logicznego zawierają predykaty logiczne, które są reprezentowane jako wyrażenia czytelne dla człowieka nazywane ciągami predykatów.

Przykłady ciągów predykatu:

Ciąg predykatu Opis
Description HAS 'hello world' true dla zdarzeń zawierających frazę hello world we właściwości Description we wszystkich źródłach zdarzeń
'hello world' true dla zdarzeń zawierających frazę hello world
startsWith(Status, 'go') true dla zdarzeń ze stanem rozpoczynającym się od go
endsWith(Status, 'oD') true dla zdarzeń ze stanem kończącym się na od
startsWith_cs(Status, 'Go') true dla zdarzeń ze stanem rozpoczynającym się od Go
endsWith_cs(Status, 'od') true dla zdarzeń ze stanem rozpoczynającym się od od
matchesRegex(s, '^G*') true dla zdarzeń ze stanem zgodnym z wyrażeniem regularnym ^G*
PointValue.Double = 3.14 true dla zdarzeń o podwójnej wartości PointValue równej 3.14
Status IN ('Good','Bad') true dla zdarzeń ze stanem zawierającym Good lub Bad
PointValue > 3.14 AND Status.String = 'Good' true dla zdarzeń o wartości PointValue większej niż 3.14 i stanu ciągu Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world' true dla zdarzeń o wartości PointValue większej niż 3.14 i stanGood lub Bad i Opis nie zawiera frazy hello world 
{ "predicateString": "PointValue.Double = 3.14" }

Wyrażenie w ciągu predykatu jest obliczane w wyrażeniu logicznym JSON. Powinna być zgodna z następującą (uproszczoną) gramatyką:

Wyrażenie logiczne JSON Formularz Backus–Naur
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 pierwotne typy danych są obsługiwane w wyrażeniach ciągu predykatu.

W przeciwieństwie do wyrażeń odwołań do właściwości JSON można pominąć typ właściwości, w tym przypadku typ jest automatycznie wnioskowany.

Obsługiwane literały

Typ pierwotny Literały
Bool TRUE, FALSE
Data/godzina dt'2016-10-08T03:22:55.3031599Z'
Double 1.23, 1.0
Ciąg 'abc'
przedział_czasu ts'P1Y2M3DT4M5.67S'
NULL

Obsługiwane typy operandów

Operacja Obsługiwane typy Uwagi
<, >, <=, >= Double, DateTime, TimeSpan
=, !=, <> String, Bool, Double, DateTime, TimeSpan, NULL <> jest odpowiednikiem !=
+, -, *, / Double, DateTime, TimeSpan
CALA String, Bool, Double, DateTime, TimeSpan, NULL Wszystkie operandy powinny mieć ten sam typ lub być stałą NULL . Wiele wartości NULLjest równoważne pojedynczej wartości NULL.
HSA Ciąg Tylko literały ciągów stałych są dozwolone po prawej stronie. Pusty ciąg i wartość NULL są niedozwolone.

W przypadku predykatów porównania (<, >, <=, =, >=, !=) i predykatu IN operand może mieć wartość NULL lub mieć jeden typ.

W przypadku wyrażeń z predykatem HAS literał stały po prawej stronie operandu HAS można rozszerzyć na wiele typów. Ponadto literał stałej po prawej stronie operandu HAS jest analizowany do wartości logicznej, podwójnej, daty/godziny lub przedziału czasu . Dla każdej pomyślnie przeanalizowanej wartości zostanie utworzony predykat z operatorem = . Te predykaty i oryginalny predykat HAS są przyłączone do predykatu OR . Na przykład ciąg p1 HAS '1.0' predykatu jest odpowiednikiem p1.String HAS '1.0' OR p1.Double = 1.0właściwości , jeśli istnieją właściwości p1 z typami String i Double .

Sprawdzanie typów

Wyrażenia predykatu są sprawdzane i sprawdzane pod kątem poprawności, aby upewnić się, że typy po prawej i lewej stronie są zgodne.

Ważne

  • Gdy stałe z lewej i prawej strony operandu nie są zgodne, zgłaszany jest błąd.
  • Błąd jest również zgłaszany, jeśli operacja nie jest dozwolona dla określonych typów lub między nimi.

  • Jeśli typ jest określony dla właściwości, jest stosowane sprawdzanie typu:

    • Każdy typ właściwości jest akceptowany względem literału NULL .

    • W przeciwnym razie typy po lewej stronie i prawej stronie powinny być zgodne.

      Przykłady właściwości p1 i p2 typu Ciąg oraz właściwość p3 typu Double są wyświetlane w poniższej tabeli:

      Ciąg predykatu Czy jest prawidłowy? Uwagi
      p1.String = 'abc' Tak
      p1.String = p2.String Tak
      p1.String = NULL Tak NULL pasuje do dowolnego typu po lewej stronie.
      p3.Double = 'abc' Nie Niezgodność.
      p3.Double = p1.String Nie Niezgodność.
      p1.String HAS 'abc' Tak
      p3.Double HAS '1.0' Tak Literał ciągu został pomyślnie przeanalizowany do wartości podwójnej .

  • Jeśli typ zostanie pominięty dla właściwości, ale zostanie określona nazwa, są wykonywane następujące kroki:

    1. Wszystkie właściwości o określonej nazwie i typach są pobierane.
    2. Operandy po lewej stronie i po prawej stronie są grupowane w parach według typu.
    3. Pary są łączone przy użyciu operacji AND .

    • Przykłady właściwości p1 i p2 typów String i Double oraz niektóre z ich odpowiedników są wyświetlane w poniższej tabeli:

      Ciąg predykatu Równoważny ciąg predykatu o silnych typach Uwagi
      p1 = 'abc' p1.String = 'abc'
      p1 = true Brak właściwości p1 typu Bool, więc jest emitowany błąd brakującej właściwości.
      p1 = NULL p1.String = NULL AND p1.Double = NULL W NULL przypadku prawej strony zakłada się, że wszystkie pasujące właściwości powinny mieć wartość NULL.
      p1 != NULL p1.String != NULL OR p1.Double != NULL Jest to inwersja poprzedniego wyrażenia.
      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 Jest to odpowiednik .p1 = NULL
      p1 HAS '1.0' p1.String HAS '1.0' OR p1.Double = 1.0 Literał ciągu został pomyślnie przeanalizowany do prawidłowej wartości podwójnej .
      p1 HAS 'true' p1.String HAS 'true' Literał ciągu został pomyślnie przeanalizowany do wartości logicznej, ale nie p1. Właściwość logiczna istnieje.
      p1 = p2 p1.String = p2.String AND p1.Double = p2.Double
      p1 != p2 p1.String != p2.String OR p1.Double != p2.Double Jest to inwersja poprzedniego wyrażenia.

  • Zarówno nazwa właściwości, jak i typ można pominąć dla właściwości po lewej stronie, jeśli typ właściwości po prawej stronie jest dobrze zdefiniowany. Jest to prawdą, gdy po prawej stronie znajdują się literały stałe i nie zawierają tylko NULL literału.

    • Ten scenariusz to uogólnienie wyszukiwania pełnotekstowego, które używa operandu HAS .

    • Wszystkie właściwości zgodne z typem po prawej stronie są tworzone, a wyrażenia wynikowe są łączone za pośrednictwem operacji OR .

    • Przykłady właściwości p1 typów String i Double oraz właściwości p2 typów String i DateTime są wyświetlane w poniższej tabeli:

      Ciąg predykatu Równoważny ciąg predykatu o silnych typach Uwagi
      = 'abc' p1.String = 'abc' OR p2.String = 'abc'
      != 'abc' p1.String != 'abc' AND p2.String != 'abc' Inwersja poprzedniego wyrażenia
      = 1.0 p1.Double = 1.0
      = dt'2000-01-02T03:04:05' p2.DateTime = dt'2000-01-02T03:04:05'
      = true Błąd. Nie istnieje żadna właściwość logiczna , więc jest emitowany błąd brakującej właściwości.
      = NULL Błąd. Pominięcie nazwy NULL właściwości po prawej stronie jest niedozwolone.
      IN (NULL) Taki sam jak poprzedni błąd.
      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' Nie ma właściwości typu Bool.

  • Jeśli operator zostanie pominięty wraz z nazwą właściwości, zakłada się, że HAS operacja.

Funkcje skalarne

Funkcje skalarne zwracają wartości skalarne.

Funkcje natywne

Funkcje skalarne, które są obsługiwane poza ramą przez Azure Time Series Insights Gen1, obejmują:

Nazwa funkcji Wartość zwracana Argumenty Przykład Uwagi
Utcnow Data/godzina Brak utcNow() Zwraca bieżący czas w formacie UTC. W nazwie funkcji jest uwzględniana wielkość liter.

Funkcja UTC zwraca teraz wartość DateTime , która zawiera bieżącą godzinę w formacie UTC. Nie akceptuje żadnych argumentów.

Wyrażenia agregujące

Wyrażenia agregacji są używane do partycjonowania kolekcji zdarzeń i miar obliczeniowych na partycjach. Wyrażenia agregacji są podzielone na następujące rodzaje:

Wyrażenia wymiarów

Wyrażenia wymiarów wewnątrz klauzuli agregacji służą do partycjonowania zestawu zdarzeń i przypisywania klucza skalarnego do każdej partycji.

Typy wyrażeń wymiarów:

Nazwa właściwości w formacie JSON Opis Przykład
Uniquevalues Wartości wymiarów w wyniku są dokładnymi wartościami danej właściwości.
dateHistogram Wartości wymiarów w wyniku to zakresy czasu danej właściwości. Histogram daty znacznika czasu może spowodować powstanie 10-godzinnych zakresów dla 10-godzinnego zakresu wyszukiwania.
numericHistogram Wartości wymiarów w wyniku to zakresy wartości w danej właściwości. Histogram liczbowy temperatury może spowodować zwrócenie 10 zakresów stopni.

Azure Time Series Insights Gen1 ogranicza maksymalną kardynalność lub maksymalny rozmiar kraty wejściowej zapytania agregowanego do 150 000 komórek. Aby obliczyć kardynalność zapytania agregowanego, należy pomnożyć rozmiary wszystkich wymiarów w zapytaniu. Jeśli produkt jest mniejszy niż 150 000, zapytanie jest akceptowane do wykonania. Jeśli produkt jest równy lub mniejszy niż 150 000, zapytanie zostanie odrzucone.

Można określić maksymalny rozmiar wymiaru, który jest generowany przez uniqueValues i numericHistogram przy użyciu klauzuli take . W dacieHistogram rozmiar jest obliczany przez podzielenie zakresu wyszukiwania według rozmiaru interwału dateHistogramu określonego przy użyciu klauzuli break .

Na przykład zapytanie agregacji ma ustawiony zakres wyszukiwania z "2017-11-15T16:00:00.000Z" na "2017-11-15T19:00:00.000Z" = 3 godziny. Jeśli zapytanie zawiera parametr dateHistogram z klauzulą break , ustaw wartość 1 minuty (wymiar 1) i wartości uniqueValue dla właściwości XYZ, rozmiar wymiaru dateHistogram wynosi 3x60=180. Ten wynik oznacza, że wartości uniqueValue mogą zająć do 150 000/180 = 833 elementów łącznie.

Wyrażenia unikatowych wartości

Wyrażenie unikatowych wartości służy do grupowania zestawu zdarzeń według wartości określonej właściwości zdarzenia.

Ocena tego wyrażenia JSON powoduje do 100 rekordów, które są pogrupowane według sensorId właściwości String.

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

Wyrażenia histogramu daty

Wyrażenie histogramu daty służy do grupowania wartości właściwości DateTime w zasobniki o określonym rozmiarze.

Ocena tego wyrażenia JSON powoduje wyświetlenie zestawu rekordów sygnatury czasowej , które są zaokrąglone pod względem podłogi, tak aby każda wartość wyzerowała sekundy.

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

Wyrażenia histogramu liczbowego

Wyrażenie histogramu liczbowego służy do grupowania podwójnych wartości właściwości w określoną liczbę zasobników.

Ocena tego wyrażenia JSON powoduje utworzenie 10 rekordów, więc zakres między wartościami minimalnymi i maksymalnymi właściwości p1 jest podzielony na 10 zasobników.

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

Wyrażenia miar

Wyrażenia miar są używane wewnątrz klauzul agregacji , aby obliczyć wartość skalarną w zestawie zdarzeń. Na przykład wyrażenie miary to obliczenie maksymalnej wartości mierzonej przez czujnik temperatury w ciągu ostatnich 24 godzin.

Wyrażenie count służy do obliczania liczby zdarzeń w odpowiednim zasobniku.

{ "count": {} }

Aby obliczyć minimalną, maksymalną, średnią i sumę wartości dla określonej właściwości w odpowiednim zasobniku, należy użyć wyrażeń minimalnych, maksymalnych, średnich i sum. 

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

Przy użyciu wyrażeń pierwszej i ostatniej miary można uzyskać wartość określonej właściwości A , która odpowiada minimalnej lub maksymalnej wartości właściwości B.

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

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

Klauzula orderBy jest opcjonalna i domyślnie jest ustawiona na właściwość Znacznik czasu$ts. Dane wejściowe mogą być dowolnego typu. Klauzula orderBy obsługuje tylko typy Double i DateTime .

Jeśli właściwość B jest typem DateTime , uzyskasz najnowszą lub najwcześniejszą wartość właściwości A.

Możesz użyć wyrażeń pierwszych i ostatnich , aby lepiej zrozumieć najwcześniejszą lub najnowszą wartość określonej właściwości. Jeśli na przykład masz właściwość o nazwie deviceID i chcesz poznać najnowsze deviceID , które wysłało zdarzenie, ostatnim operatorem wyrażeń jest najbardziej wydajny operator wyrażeń używany do identyfikowania tych informacji.

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

Innym przykładem jest użycie ostatniego do znalezienia ostatniej zgłoszonej lokalizacji określonego obiektu, takiego jak statek, pojazd lub inny obiekt ruchomy.

Aby zilustrować zapytanie, które tworzy ostatnią znaną lokalizację statków we flocie, można utworzyć zapytanie podobne do następującego:

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

Innym przykładem jest użycie najpierw do znalezienia urządzenia, które zgłasza najniższe ciśnienie dla każdego zakładu:

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

Obsługa wymiarów i typów miar

Oto obsługiwane wyrażenia wymiarów i miar na podstawie typu właściwości:

Typ właściwości Obsługiwane wyrażenia wymiarów Obsługiwane wyrażenia miar
Bool "uniqueValues" "first" (dane wejściowe), "last" (dane wejściowe)
Data/godzina "uniqueValues", "dateHistogram" "min", , "max""first" (orderBy, input), "last” (orderBy, input)
Double "uniqueValues", "numericHistogram" "sum", , "avg", "min", "first""max"(orderBy, input), "last” (orderBy, input)
Ciąg "uniqueValues" "first" (dane wejściowe), "last" (dane wejściowe)

Klauzule

Klauzule tworzą składniki składników zapytań JSON lub część wyrażenia. Klauzule są podzielone na następujące rodzaje:

Klauzule zakresu wyszukiwania

Klauzula zakresu wyszukiwania służy do filtrowania wbudowanej właściwości znacznika czasu zdarzenia do danego interwału. Początek interwału jest uwzględniany. Koniec interwału jest wyłączny.

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

Właściwości from i do w klauzuli search span (searchSpan) powinny być prawidłowymi wyrażeniami typu wyniku DateTime . Te wyrażenia są oceniane przed wykonaniem zapytania, co oznacza, że nie powinny zawierać żadnych odwołań do właściwości.

Klauzule predykatu

Klauzula predykatu służy do filtrowania zdarzeń spełniających predykat. Należy go rozpoznać w wyrażeniu logicznym .

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

Aby filtrować zdarzenia, oznacza uruchomienie predykatu reprezentowanego przez wyrażenie logiczne dla każdego zdarzenia w środowisku. Wykonanie wyrażenia na zdarzeniu zwraca true wartość , jeśli zdarzenie musi zostać uwzględnione w dalszych operacjach. Zwraca false wartość , jeśli zdarzenie musi zostać pominięte z dalszego przetwarzania.

Uwaga

Zdarzenia są zawsze filtrowane według zakresu wyszukiwania oprócz filtrowania określonego w wyrażeniu predykatu.

Ogranicz najważniejsze klauzule

Aby uzyskać określoną liczbę wartości w kolejności rosnącej lub malejącej, należy użyć klauzuli *limit top . Liczba wartości jest ograniczona zgodnie z określoną liczbą.

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

Ogranicz klauzule take

Możesz użyć klauzuli limit take jako szybkiego sposobu uzyskania zestawu wartości w żadnej określonej kolejności. Liczba zwracanych wartości jest ograniczona przez określone dane wejściowe.

{ "take": 10 }

Ogranicz przykładowe klauzule

Aby uzyskać statystycznie reprezentatywną próbkę z zestawu wartości, należy użyć klauzuli *limit sample . Liczba zwracanych wartości jest ograniczona przez określone dane wejściowe.

{ "sample": 10 }

Klauzule break

Aby określić sposób dzielenia zakresu, należy użyć klauzuli *break w wyrażeniach histogramu.

W przypadku histogramów dat należy określić rozmiar interwału daty/godziny i granic interwału. Można to zrobić, chyba że histogram jest oparty na wbudowanej właściwości Sygnatura czasowa , w której granice są określane na podstawie zakresu wyszukiwania:

  • Granice interwałów są opcjonalne i mogą być używane. Można ich na przykład użyć, gdy są one określane na podstawie zakresu wyszukiwania, jeśli nie zostaną pominięte granice interwału.
  • W przypadku histogramów liczbowych należy określić liczbę podziałów. Granice interwałów określa się na podstawie minimalnych i maksymalnych wartości właściwości.
{
  "breaks": {
    "size": "1d",
    "from": "2000-01-02T03:04:05.0000000",
    "to": "2000-01-02T03:04:05.0000000"
  }
}

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

Klauzule agregacji

Klauzula agregacji służy do partycjonowania zestawu zdarzeń według danej właściwości podczas mierzenia wartości innych właściwości zdarzenia.

Miary są oceniane na każdej partycji utworzonej przez wyrażenie wymiaru.

  • Poniższy przykład JSON oblicza średnią, minimalną i maksymalną temperaturę na identyfikator czujnika.

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

    Uwaga

    Klauzula aggregates to tablica, która umożliwia określenie więcej niż jednej agregacji na najwyższym poziomie.

  • Poniższy przykład w formacie JSON oblicza średnią temperaturę na miasto i producenta niezależnie:

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

    Uwaga

    • Posiadanie więcej niż jednego elementu w tablicy agregacji nie jest obecnie obsługiwane.
    • Jednak definicja agregacji może zawierać macierz zagnieżdżona, która określa bardziej elastyczną, wielowymiarową kratę.

  • Poniższy przykład JSON oblicza średnią temperaturę na identyfikator czujnika, na minutę.

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

Zobacz też