sintassi della query Azure Time Series Insights Gen1

Attenzione

È un articolo di Gen1.

Questo articolo descrive il formato e la sintassi della richiesta di query per l'API query di Azure Time Series Insights Gen1.

Riepilogo

Importante

• Le richieste di query devono essere in formato JSON.
• I payload delle richieste HTTP eseguiti nell'API query devono essere conformi al formato specificato in questo articolo.

La lingua è suddivisa negli elementi seguenti:

• Espressioni scalari, che producono valori scalari. Le espressioni scalari includono espressioni stringa predicato, espressioni di confronto e espressioni aritmetiche.
• Funzioni scalari, che restituiscono valori scalari.
• Espressioni di aggregazione, usate per partizionare raccolte di eventi e misure di calcolo sulle partizioni.
• Clausole, che costituiscono i componenti costitutivi delle query JSON o una parte di un'espressione.

Modello di dati

L'API query di Azure Time Series Insights Gen1 opera sui dati archiviati come singoli eventi all'interno di un ambiente. Ogni evento è un set di coppie nome proprietà e valore .

Proprietà degli eventi

Le proprietà dell'evento possono essere di uno dei tipi primitivi seguenti: Bool, DateTime, Double o String. Tutti i tipi primitivi sono nullable.

Nota

I formati di origine eventi personalizzati possono supportare un set più ampio di tipi di valore. Azure Time Series Insights Gen1 inferisce il tipo primitivo più vicino e quindi esegue il cast dei tipi personalizzati in ingresso.

Tutti gli eventi hanno le proprietà predefinite seguenti con un nome e un tipo predefiniti:

Nome proprietà	Tipo di proprietà	Definizione
$ts	DateTime	Timestamp evento
$esn	Stringa	Nome origine evento

• Timestamp evento

  Per impostazione predefinita, viene fornito un valore timestamp evento dall'origine evento. Ad esempio, gli eventi provenienti da un hub IoT avranno il tempo previsto come timestamp.

  I clienti possono modificare questo comportamento configurando invece un'altra proprietà evento. Le proprietà timestamp personalizzate possono essere specificate negli hub eventi e negli hub IoT.

• Nome origine evento

  Il nome dell'origine evento è il nome visualizzato per l'origine evento da cui Azure Time Series Insights Gen1 ha ricevuto l'evento. I nomi dell'origine evento sono associati a un evento specifico in ingresso.

  Importante

  • I nomi dell'origine evento rimangono invariati per la durata dell'evento.
  • Se il nome di un'origine evento viene modificato, gli eventi esistenti contengono il nome dell'origine evento precedente. I nuovi eventi porteranno il nuovo nome dell'origine evento.

Tipi di eventi

Le proprietà degli eventi personalizzate vengono identificate in modo univoco e a cui si fa riferimento nelle espressioni di query in base al nome e al tipo. Un evento può avere più proprietà con lo stesso nome e tipi diversi. Le proprietà con lo stesso nome, ma tipi diversi potrebbero causare la suddivisione dei tipi in ingresso.

Un valore della proprietà evento di tipo String può essere archiviato come proprietà con un tipo diverso nei casi seguenti:

• Se un valore String è un valore Double valido, viene archiviato come Double e String.
• Se un valore String è un valore DateTime valido, viene archiviato solo come DateTime .

L'API Query converte valori letterali stringhe vuote ("") nell'output null .

Azure Time Series Insights Gen1 ha un supporto limitato per i valori seguenti all'interno del tipo Double: Double.NaN, Double.PositiveInfinitye Double.NegativeInfinity. Questi valori vengono convertiti null in durante l'ingresso, ma se la valutazione della query produce uno di questi valori, il valore viene valutato e serializzato come stringa in risposta.

È possibile passare questi valori come stringhe per l'ingresso, quindi nelle espressioni di query questi valori devono essere passati anche come stringhe.

Gli schemi eventi descrivono le proprietà di un evento. Uno schema di eventi contiene il nome di un'origine evento e il set ordinato di proprietà per l'evento. Gli eventi diversi possono avere schemi diversi o condividere lo stesso schema.

Espressioni scalari

Le espressioni scalari producono valori scalari. Le espressioni scalari sono suddivise nei tipi seguenti:

• Espressioni costanti
• Espressioni di riferimento delle proprietà
• Espressioni di confronto
• Espressioni aritmetiche
• Espressioni di stringa predicato

Espressioni costanti

Si rappresentano espressioni costanti usando i valori letterali seguenti per ognuno dei tipi primitivi:

Tipo primitivo	Rappresentazione JSON	Esempio di JSON	Note
Bool	Tipo booleano JSON	true, false
DateTime	Come oggetto annidato con una singola proprietà dateTime in formato yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFKISO 8601 .	{"dateTime":"2016-08-01T00:00:00.000Z"}
Double	Numero JSON eseguito nel cast dell'intervallo Double.	1.23e45, 123	I doppio overflow genereranno un errore.
Stringa	Tipo di stringa JSON	"abc"
TimeSpan	Come oggetto annidato con una proprietà timeSpan singola in formato ISO 8601 : P[n]Y[n]M[n]DT[n]H[n]M[n]S.	{"timeSpan":"P1Y2M3DT4M5.67S"}

Tipi primitivi nullable

I tipi di dati primitivi sono nullable. null i valori per i tipi primitivi vengono espressi in JSON come segue:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Espressioni di riferimento delle proprietà

Si usa un'espressione di riferimento delle proprietà per accedere ai valori delle proprietà non predefinite di un evento. Le proprietà non predefinite includono qualsiasi proprietà personalizzata oltre quelle predefinite contenute automaticamente in uno schema eventi.

Il tipo di risultato di un'espressione di riferimento della proprietà è il tipo primitivo della proprietà. Le proprietà nello schema eventi sono identificate in modo univoco in base al nome e al tipo e l'espressione di riferimento deve essere specificata entrambe.

• Esempi JSON:

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

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

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

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

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

Un'espressione di riferimento delle proprietà predefinita viene usata per accedere alle proprietà predefinite di un evento. Le proprietà predefinite sono solo quelle definite automaticamente in uno schema eventi.

Il tipo di risultato di un'espressione di riferimento della proprietà predefinita è il tipo primitivo della proprietà. Le proprietà predefinite sono a cui si fa riferimento solo per nome; pertanto, nessun tipo è necessario nell'espressione di riferimento:

{ "builtInProperty": "$esn" }

Espressioni di confronto

Sono supportate le espressioni di confronto booleane seguenti:

Nome della proprietà in JSON	Descrizione
eq	Uguale a
in	In (uguale a qualsiasi)
phrase	Contiene frasi
startsWith	Inizia con
endsWith	Termina con la frase
Regex	Corrisponde all'espressione regolare
lt	Minore di
Lte	Minore o uguale a
gt	Maggiore di
Gte	Maggiore o uguale a

Importante

• Tutte le espressioni di confronto accettano i tipi primitivi di argomenti a sinistra e di destra e restituiscono un valore booleano che rappresenta il risultato del confronto.
• Entrambi i tipi di argomenti a sinistra e di destra nei confronti devono corrispondere.
• Tutti i tipi eseguono il cast implicito solo a se stessi e i cast espliciti non sono supportati.

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

• Esempi 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"
     }
  }
  

La tabella seguente illustra i tipi supportati di argomenti per ognuna delle espressioni di confronto:

Tipo di argomento	Operazione di confronto supportata
Bool	eq, in
DateTime	eq, in, lt, lte, gte
Double	eq, in, lt, lte, gte
Stringa	eq, in, frase, startsWith, endWith, regex
TimeSpan	eq, in, lt, lte, gte

Il valore letterale NULL può essere usato solo con gli operatori di confronto seguenti: eq o in.

• L'operatore eq genera se true entrambi i lati sono null valori. In caso contrario, l'operatore restituisce false.
• Per altre operazioni, l'errore viene generato per il valore letterale NULL e il comportamento non è definito per le proprietà null-value (qualsiasi operazione di confronto che genera false).
• Un null valore precede i valori non Null negli ordini di ordinamento, ad esempio se l'ordinamento in base a una proprietà viene applicato per restituire un elenco di eventi.

Azure Time Series Insights Gen1 supporta le espressioni logiche booleane seguenti:

Nome della proprietà in JSON	Descrizione
and	Accetta un set non vuoto di argomenti booleani e restituisce se tutti i valori vengono valutati true in true.
or	Accetta un set non vuoto di argomenti booleani e restituisce se uno di essi restituisce truetrue.
not	Accetta un singolo argomento booleano e restituisce il valore negato.

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

La proprietà stringComparison è facoltativa. Per impostazione predefinita, il relativo valore è OrdinalIgnoreCase, che causa l'ignorare le maiuscole e minuscole delle frasi nei confronti.

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

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

Espressioni aritmetiche

Azure Time Series Insights Gen1 supporta le espressioni aritmetiche seguenti:

Nome della proprietà in JSON	Descrizione
add	Addizione
sub	Sottrazione
Mult	Moltiplicazione
div	Divisione

Tutte le espressioni aritmetiche accettano gli argomenti sinistro e destro dei tipi primitivi e restituiscono un valore che rappresenta il risultato dell'operazione.

Tutti i tipi eseguono il cast implicito solo a se stessi e i cast espliciti non sono supportati.

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

La tabella seguente illustra i tipi di argomenti supportati per ogni espressione aritmetica:

Operazione	Tipo sinistro	Tipo destro	Tipo di risultato
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

Espressioni stringa predicato

Le espressioni stringa del predicato booleano contengono predicati booleani rappresentati come espressioni leggibili dall'utente denominate stringhe di predicato.

Esempi di stringhe di predicato:

Stringa di predicato	Descrizione
Description HAS 'hello world'	true per gli eventi che contengono la frase hello world nella proprietà Description in tutte le origini eventi
'hello world'	true per gli eventi che contengono la frase hello world
startsWith(Status, 'go')	true per gli eventi con stato a partire da go
endsWith(Status, 'oD')	true per gli eventi con stato che termina con od
startsWith_cs(Status, 'Go')	true per gli eventi con stato a partire da Go
endsWith_cs(Status, 'od')	true per gli eventi con stato a partire da od
matchesRegex(s, '^G*')	true per gli eventi con Stato che corrisponde all'espressione regolare ^G*
PointValue.Double = 3.14	true per gli eventi con double PointValue uguale a 3.14
Status IN ('Good','Bad')	true per gli eventi con stato che contiene Good o Bad
PointValue > 3.14 AND Status.String = 'Good'	true per gli eventi con PointValue maggiore di 3.14 e stato stringa di Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'	true per gli eventi con PointValue maggiore di 3.14 e Stato di Good o Bad e Descrizione non contenente la frase hello world

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

L'espressione nella stringa del predicato viene valutata in un'espressione booleana JSON. Deve essere conforme alla grammatica seguente (semplificata):

Espressione booleana JSON	Modulo 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 tipi di dati primitivi Gen1 sono supportati nelle espressioni stringa di predicato.

A differenza delle espressioni di riferimento alle proprietà JSON, è possibile omettere un tipo per una proprietà, nel qual caso viene dedotto automaticamente un tipo.

Valori letterali supportati

Tipo primitivo	Valori letterali
Bool	TRUE, FALSE
DateTime	dt'2016-10-08T03:22:55.3031599Z'
Double	1.23, 1.0
Stringa	'abc'
TimeSpan	ts'P1Y2M3DT4M5.67S'
	NULL

Tipi di operando supportati

Operazione	Tipi supportati	Note
<, >, <=, >=	Double, DateTime, TimeSpan
=, !=, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> è equivalente per !=
+, -, *, /	Double, DateTime, TimeSpan
IN	String, Bool, Double, DateTime, TimeSpan, NULL	Tutti gli operandi devono essere dello stesso tipo o devono essere costanti NULL . Più valori NULLsono equivalenti a un singolo valore NULL.
HA	Stringa	Sono consentiti solo valori letterali di tipo stringa costante sul lato destro. Le stringhe vuote e NULL non sono consentite.

Per i predicati di confronto (, >,<<=, >=, =, !=) e l'operando del predicato IN può essere NULL o avere un singolo tipo.

Per le espressioni con un predicato HAS , il valore letterale costante sul lato destro dell'operando HAS può essere espanso in più tipi. Inoltre, il valore letterale costante a destra dell'operando HAS viene analizzato in un valore Bool, Double, DateTime o TimeSpan . Per ogni valore analizzato correttamente, viene creato un predicato con l'operatore = . Questi predicati e il predicato HAS originale vengono uniti in un predicato OR . Ad esempio, una stringa p1 HAS '1.0' di predicato equivale a p1.String HAS '1.0' OR p1.Double = 1.0, se esistono proprietà p1 con tipi String e Double .

Controllo del tipo

Le espressioni di predicato sono controllate dal tipo e convalidate per garantire che i tipi di destra e di sinistra corrispondano.

Importante

• Quando le costanti a sinistra e a destra di un operando non corrispondono, viene generato un errore.
• Viene generato anche un errore se un'operazione non è consentita in o tra tipi specifici.

• Se per la proprietà viene specificato un tipo, viene applicato un controllo del tipo:

  • Qualsiasi tipo di proprietà viene accettato in base a un valore letterale NULL .

  • In caso contrario, i tipi lato sinistro e destro devono corrispondere.

    Nella tabella seguente sono visualizzati esempi di proprietà p1 e p2 del tipo String e della proprietà p3 del tipo Double :

    Stringa di predicato	È valido?	Note
    p1.String = 'abc'	Sì
    p1.String = p2.String	Sì
    p1.String = NULL	Sì	NULL corrisponde a qualsiasi tipo di lato sinistro.
    p3.Double = 'abc'	No	Tipo non corrispondente.
    p3.Double = p1.String	No	Tipo non corrispondente.
    p1.String HAS 'abc'	Sì
    p3.Double HAS '1.0'	Sì	Il valore letterale stringa è stato analizzato correttamente in un valore Double .

• Se un tipo viene omesso per la proprietà ma viene specificato un nome, vengono eseguiti i passaggi seguenti:

  1. Vengono acquisite tutte le proprietà con un nome e tipi specificati.
  2. Gli operandi lato sinistro e destro sono raggruppati in coppie per tipo.
  3. Le coppie vengono concatenate usando le operazioni AND .

  • Nella tabella seguente vengono visualizzati esempi di proprietà p1 e p2 dei tipi String e Double e alcuni dei relativi equivalenti:

    Stringa di predicato	Stringa di predicato con tipo sicuro equivalente	Note
    p1 = 'abc'	p1.String = 'abc'
    p1 = true		Nessuna proprietà p1 di tipo Bool, quindi viene generato un errore di proprietà mancante.
    p1 = NULL	p1.String = NULL AND p1.Double = NULL	Per NULL il lato destro si presuppone che tutte le proprietà corrispondenti debbano essere NULL.
    p1 != NULL	p1.String != NULL OR p1.Double != NULL	Si tratta di un'inversione dell'espressione precedente.
    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	Si tratta dell'equivalente di p1 = NULL.
    p1 HAS '1.0'	p1.String HAS '1.0' OR p1.Double = 1.0	Il valore letterale stringa è stato analizzato correttamente in un valore Double valido.
    p1 HAS 'true'	p1.String HAS 'true'	Il valore letterale stringa è stato analizzato correttamente in Bool, ma non p1. Esiste la proprietà Bool .
    p1 = p2	p1.String = p2.String AND p1.Double = p2.Double
    p1 != p2	p1.String != p2.String OR p1.Double != p2.Double	Si tratta di un'inversione dell'espressione precedente.

• Sia il nome della proprietà che il tipo possono essere omessi per una proprietà lato sinistra se il tipo di proprietà lato destro è ben definito. Questo è vero ogni volta che il lato destro ha valori letterali costanti e non contiene solo un NULL valore letterale.

  • Questo scenario è una generalizzazione della ricerca full-text che usa l'operando HAS .

  • Tutte le proprietà corrispondenti al tipo lato destro vengono prese e le espressioni risultanti vengono concatenate tramite un'operazione OR .

  • Gli esempi di proprietà p1 dei tipi String e Double e della proprietà p2 dei tipi String e DateTime vengono visualizzati nella tabella seguente:

    Stringa predicato	Stringa di predicato con tipo sicuro equivalente	Note
    = 'abc'	p1.String = 'abc' OR p2.String = 'abc'
    != 'abc'	p1.String != 'abc' AND p2.String != 'abc'	Inversione dell'espressione precedente
    = 1.0	p1.Double = 1.0
    = dt'2000-01-02T03:04:05'	p2.DateTime = dt'2000-01-02T03:04:05'
    = true		Errore. Nessuna proprietà Bool esiste, quindi viene generato un errore di proprietà mancante.
    = NULL		Errore. Non è consentito omettere il nome della proprietà per NULL il lato destro.
    IN (NULL)		Uguale all'errore precedente.
    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'	Non esiste alcuna proprietà con tipo Bool.

• Se l'operatore viene omesso insieme a un nome di proprietà, si presuppone che l'operazione HAS venga eseguita.

Funzioni scalari

Le funzioni scalari restituiscono valori scalari.

Funzioni native

Le funzioni scalari supportate da Azure Time Series Insights Gen1 includono:

Nome della funzione	Valore restituito	Argomenti	Esempio	Note
utcNow	DateTime	Nessuno	utcNow()	Restituisce l'ora corrente in formato UTC. Il nome della funzione è distinzione tra maiuscole e minuscole.

La funzione UTC restituisce ora un valore DateTime che contiene l'ora corrente in formato UTC. Non accetta argomenti.

Espressioni di aggregazione

Le espressioni di aggregazione vengono usate per partizionare raccolte di eventi e misure di calcolo sulle partizioni. Le espressioni di aggregazione sono suddivise nei tipi seguenti:

• Espressioni di dimensione
• Espressioni di valori univoci
• Espressioni istogrammi data
• Espressioni di misura

Espressioni di dimensione

Si usano espressioni di dimensione all'interno di una clausola di aggregazione per partizionare un set di eventi e assegnare una chiave scalare a ogni partizione.

Tipi di espressione dimensione:

Nome della proprietà in JSON	Descrizione	Esempio
uniqueValues	I valori delle dimensioni nel risultato sono valori esatti di una determinata proprietà.
dateHistogram	I valori delle dimensioni nel risultato sono intervalli di tempo di una determinata proprietà.	L'istogramma di data del timestamp potrebbe comportare intervalli di 10 ore per un intervallo di ricerca di 10 ore.
numericHistogram	I valori delle dimensioni nel risultato sono intervalli di valori in una determinata proprietà.	L'istogramma numerico della temperatura potrebbe causare un ritorno di 10 intervalli di gradi.

Azure Time Series Insights Gen1 limita la cardinalità massima o la dimensione massima del reticolo, di una query di aggregazione di input a 150.000 celle. Per calcolare la cardinalità di una query di aggregazione, moltiplicare le dimensioni di tutte le dimensioni della query. Purché il prodotto sia minore di 150.000, la query viene accettata per l'esecuzione. Se il prodotto è uguale o minore di 150.000, la query viene rifiutata.

Specificare la dimensione massima di una dimensione prodotta da uniqueValues e numericHistogram usando la clausola take . In dateHistogram le dimensioni vengono calcolate suddividendo l'intervallo di ricerca in base alle dimensioni dell'intervallo dateHistogram , specificato usando la clausola interruzioni .

Ad esempio, una query di aggregazione ha l'intervallo di ricerca impostato da "2017-11-15T16:00:00.000Z" a "2017-11-15T19:00:00.000Z" = 3 ore. Se la query include dateHistogram con la clausola di interruzione , impostare su 1 minuto (dimensione 1) e uniqueValues sulla proprietà XYZ, la dimensione dateHistogram è 3x60=180. Questo risultato significa che uniqueValues può richiedere fino a 150.000/180 = 833 elementi totali.

Espressioni di valori univoci

Si usa un'espressione valori univoci per raggruppare un set di eventi in base ai valori di una proprietà evento specificata.

La valutazione di questa espressione JSON comporta un massimo di 100 record, raggruppati in base alla sensorId proprietà String.

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

Espressioni istogrammi data

Si usa un'espressione istogramma di data per raggruppare i valori delle proprietà DateTime in bucket di una dimensione specificata.

Una valutazione di questa espressione JSON comporta un set di record Timestamp arrotondati a piano in modo che ogni valore abbia zero secondi.

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

Espressioni istogrammi numeriche

Si usa un'espressione istogramma numerica per raggruppare i valori delle proprietà Double in un numero specificato di bucket.

Una valutazione di questa espressione JSON comporta 10 record, quindi l'intervallo tra i valori minimi e massimi della proprietà p1 è diviso in 10 bucket.

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

Espressioni di misura

Si usano espressioni di misura all'interno di clausole aggregate per calcolare un valore scalare in un set di eventi. Ad esempio, un'espressione di misura è il calcolo del valore massimo misurato da un sensore di temperatura negli ultimi 24 ore.

Si usa un'espressione di conteggio per calcolare il numero di eventi all'interno di un bucket corrispondente.

{ "count": {} }

Si usano espressioni min, max, avg e sum per calcolare il valore minimo, massimo, medio e somma dei valori per una proprietà specificata all'interno di un bucket corrispondente.

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

Con le espressioni di prima e ultima misura, è possibile ottenere il valore di una proprietà specificata A che corrisponde al valore minimo o massimo della proprietà B.

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

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

La clausola orderBy è facoltativa e viene impostata per impostazione predefinita sulla proprietà Timestamp$ts. L'input può essere di qualsiasi tipo. La clausola orderBy supporta solo i tipi Double e DateTime .

Se la proprietà B è un tipo DateTime , viene visualizzato il valore più recente o il primo valore della proprietà A.

È possibile usare le prime e ultime espressioni per comprendere il valore più recente o più recente di una proprietà specifica. Ad esempio, se si dispone di una proprietà denominata deviceID e si vuole comprendere l'ultima volta deviceID che ha inviato un evento, l'ultimo è l'operatore di espressione più efficiente da usare per identificare tali informazioni.

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

Un altro esempio consiste nell'usare l'ultima posizione segnalata di un determinato oggetto, ad esempio una nave, un veicolo o un altro oggetto in movimento.

Per illustrare una query che produce l'ultima posizione nota delle navi in una flotta, è possibile creare una query simile alla seguente:

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

Un altro esempio consiste nell'usare prima di tutto un dispositivo che segnala la pressione più bassa per ogni impianto:

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

Supporto del tipo di dimensione e misura

Di seguito sono riportate le espressioni di dimensione e misura supportate, in base al tipo di proprietà:

Tipo di proprietà	Espressioni di dimensione supportate	Espressioni di misura supportate
Bool	"uniqueValues"	"first" (input), "last" (input)
DateTime	"uniqueValues", "dateHistogram"	"min", "max", "first" (orderBy, input), "last” (orderBy, input)
Double	"uniqueValues", "numericHistogram"	"sum" "min", "avg", "max""first" (orderBy, input), "last” (orderBy, input)
Stringa	"uniqueValues"	"first" (input), "last" (input)

Clausole

Le clausole formano componenti costitutivi di query JSON o una parte di un'espressione. Le clausole sono suddivise nei tipi seguenti:

• Clausole di intervallo di ricerca
• Clausole predicate
• Limitare le clausole top
• Limitare le clausole take
• Limitare le clausole di esempio
• Clausole di interruzione
• Clausole di aggregazione

Clausole di intervallo di ricerca

Si usa una clausola di intervallo di ricerca per filtrare una proprietà Timestamp predefinita di un evento a un determinato intervallo. L'inizio dell'intervallo è inclusivo. La fine dell'intervallo è esclusiva.

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

Le proprietà da e a nella clausola di intervallo di ricerca (searchSpan) devono essere espressioni valide del tipo di risultato DateTime . Queste espressioni vengono valutate prima dell'esecuzione di query, il che significa che non devono contenere riferimenti alle proprietà.

Clausole predicate

Si usa una clausola predicato per filtrare gli eventi che soddisfano il predicato . Deve essere risolto in un'espressione booleana .

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

Per filtrare gli eventi significa eseguire un predicato rappresentato da un'espressione booleana in ogni evento nell'ambiente. L'esecuzione di un'espressione in un evento restituisce true se l'evento deve essere incluso in ulteriori operazioni. Restituisce false se l'evento deve essere omesso da un'ulteriore elaborazione.

Nota

Gli eventi vengono sempre filtrati dall'intervallo di ricerca oltre a qualsiasi filtro specificato all'interno di un'espressione predicato.

Limitare le clausole top

Si usa una clausola *limit top per ottenere un numero specificato di valori in ordine crescente o decrescente. Il numero di valori è limitato in base al conteggio specificato.

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

Limitare le clausole take

È possibile usare una clausola di accetta limite come modo rapido per ottenere un set di valori in nessun ordine specifico. Il numero di valori restituiti è limitato dall'input specificato.

{ "take": 10 }

Limitare le clausole di esempio

Si usa una clausola di esempio *limite per ottenere un campione statisticamente rappresentativo da un set di valori. Il numero di valori restituiti è limitato dall'input specificato.

{ "sample": 10 }

Clausole di interruzione

Si usa una clausola *break nelle espressioni istogrammi per specificare la modalità di divisione di un intervallo.

Per gli istogrammi di data, è necessario specificare le dimensioni dell'intervallo datetime e dei limiti di intervallo. A meno che l'istogramma non sia basato su una proprietà Timestamp predefinita in cui i limiti vengono determinati in base all'intervallo di ricerca:

• I limiti di intervallo sono facoltativi e possono essere usati. Ad esempio, è possibile usarli quando vengono determinati in base a un intervallo di ricerca se vengono omessi limiti di intervallo di intervallo.
• Per gli istogrammi numerici, è necessario specificare il numero di interruzioni. Si determinano limiti di intervallo in base ai valori minimi e massimi di una proprietà.

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

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

Clausole di aggregazione

Si usa una clausola di aggregazione per partizionare un set di eventi da una determinata proprietà mentre si misurano i valori di altre proprietà evento.

Le misure vengono valutate in ogni partizione prodotta dall'espressione della dimensione.

• L'esempio JSON seguente calcola le temperature medie, minime e massime per ID sensore.

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

  Nota

  Una clausola di aggregazione è una matrice che consente di specificare più aggregazioni a livello superiore.

• Nell'esempio JSON seguente viene calcolata la temperatura media per città e per produttore in modo indipendente:

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

  Nota

  • La presenza di più elementi in una matrice di aggregazioni non è attualmente supportata.
  • Tuttavia, una definizione di aggregazione può includere una matrice annidata che specifica un reticolo più flessibile e multidimensionale.

• Nell'esempio JSON seguente viene calcolata la temperatura media per ID sensore, al minuto.

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

Vedi anche

• Per altre informazioni sulle API di Azure Time Series Insights Gen1, vedere API Gen1.

• Per informazioni sui parametri di richiesta e autenticazione, vedere Autenticazione e autorizzazione.

• Altre informazioni su Azure Time Series Insights Gen1 esaminando la documentazione di Gen1.