sintaxe de expressão de série temporal Azure Time Series Insights Gen2

Artigo
07/19/2023

Visão geral

A expressão de série temporal (TSX) é uma linguagem de expressão baseada em cadeia de caracteres com digitação forte. O TSX é usado para representar as entidades a seguir em uma Consulta de Série Temporal.

Filtrar
Valor
Agregação

Expressões de filtro

Expressões de filtro são usadas para representar cláusulas boolianas. A tabela a seguir lista exemplos de filtros:

TSX	Descrição
`$event.PointValue.Double = 3.14`	`true` para eventos com PointValue duplo igual a `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true`para eventos com PointValue maior que `3.14` e cadeia de caracteres status `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` para eventos com um carimbo de data/hora maior que `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` para eventos com PointValue igual a `true`

Expressões de valor

As expressões de valor são usadas para representar o valor para variáveis numéricas e categóricas. Uma expressão de valor pode ser uma expressão de referência de propriedade do tipo Double ou Long.

Por exemplo:

TSX	Observações
`$event.Temperature.Double`	O último token em qualquer expressão de valor (nesse caso `Double`) é lido como o Tipo da propriedade.
`$event.Temperature`	Supõe-se que o tipo seja Double para uma propriedade acessada por um único token.
`$event['Temperature-Celsius']`	Use `[` e `]` para tokens de escape que têm caracteres especiais. Além disso, use `\` dentro dos colchetes para escapar dos seguintes caracteres: `\` e `'`.
`$event.Temperature.Celsius.Double`	Use `.` para acessar propriedades aninhadas. Ao acessar propriedades aninhadas, o Tipo é necessário.
`$event.Temperature['Celsius-C'].Double`	Use `[` e `]` para tokens de escape que têm caracteres especiais ao acessar propriedades aninhadas. Além disso, use `\` dentro dos colchetes para escapar dos seguintes caracteres: `\` e `'`. Ao acessar propriedades aninhadas, o Tipo é necessário.
`$event['Temperature']['Celsius'].Double`	O uso de `[` e `]` para tokens de escape é permitido em qualquer token.

Tipo de variável numérica

O resultado da expressão de valor deve ser do tipo Double ou Long .

Tipo de variável de agregação

O resultado da expressão de valor pode ser de qualquer tipo com suporte.

Tipo de variável categórica

O resultado da expressão de valor só pode ser o tipo String ou Long .

Expressões de agregação

Expressões de agregação são usadas para representar a operação de agregação a ser usada na consulta. Uma expressão de agregação resulta em um único valor para cada intervalo. Expressões de agregação podem ser aplicadas em variáveis numéricas e de agregação.

Expressões de agregação – tipo de variável numérica

Variáveis numéricas devem se referir a $value.

Aqui estão as funções de agregação com suporte.

Função de agregação	Exemplo	Descrição
`min`	`min($value)`	Calcula o mínimo do `$value` por intervalo. `null` Evita valores. Não pode ser usado com interpolação.
`max`	`max($value)`	Calcula o máximo do `$value` por intervalo. `null` Evita valores. Não pode ser usado com interpolação.
`sum`	`sum($value)`	Calcula a soma de `$value` em todos os eventos no intervalo. `null` Evita valores. Não pode ser usado com interpolação.
`avg`	`avg($value)`	Calcula a média de `$value` em todos os eventos no intervalo. `null` Evita valores. Não pode ser usado com interpolação.
`first`	`first($value)`	Retorna `$value` o primeiro evento que ocorre no intervalo por carimbo de data/hora do evento. Não evita`null` valores. Não pode ser usado com interpolação.
`last`	`last($value)`	Retorna `$value` o último evento que ocorre no intervalo por carimbo de data/hora do evento. Não evita`null` valores. Não pode ser usado com interpolação.
`median`	`median($value)`	Retorna `$value` o evento do meio no intervalo por carimbo de data/hora do evento. Não evita`null` valores. Não pode ser usado com interpolação.
`stdev`	`stdev($value)`	Retorna `$value` o desvio padrão dos eventos no intervalo. `null` Evita valores. Não pode ser usado com interpolação.
`twsum`	`twsum($value)`	Retorna `$value` a soma ponderada por tempo dos eventos no intervalo. Requer interpolação.
`twavg`	`twavg($value)`	Retorna `$value` a média ponderada de tempo dos eventos no intervalo. Requer interpolação.
`left`	`left($value)`	Retorna o `$value` na borda esquerda do intervalo determinado. Requer interpolação.
`right`	`right($value)`	Retorna o `$value` na borda direita do intervalo determinado. Requer interpolação.

Expressões de agregação – tipo de variável de agregação

As variáveis de agregação devem se referir a uma Propriedade no conteúdo do evento.

Aqui estão as funções de agregação com suporte.

Função de agregação	Exemplo	Descrição
`count`	`count()`	Retorna o número de eventos por intervalo.
`min`	`min($event.Temperature.Double)`	Calcula o mínimo da propriedade Temperatura por intervalo. `null` Evita valores.
`max`	`max($event.Temperature.Long)`	Calcula o máximo da propriedade Temperatura por intervalo. `null` Evita valores.
`sum`	`sum($event.Temperature.Double)`	Calcula a soma da propriedade Temperatura em todos os eventos no intervalo. `null` Evita valores.
`avg`	`avg($event.Temperature.Long)`	Calcula a média da propriedade Temperatura em todos os eventos no intervalo. `null` Evita valores.
`first`	`first($event.Temperature.String)`	Retorna o primeiro valor (por carimbo de data/hora do evento) da propriedade Temperatura de todos os eventos no intervalo. Não evita`null` valores.
`last`	`last($event.Temperature.String)`	Retorna o último valor (por carimbo de data/hora do evento) da propriedade Temperatura de todos os eventos no intervalo. Não evita`null` valores.
`median`	`median($event.Temperature.String)`	Retorna o valor de ocorrência intermediária (por carimbo de data/hora do evento) da propriedade Temperatura de todos os eventos no intervalo. Não evita`null` valores.
`stdev`	`stdev($event.Temperature.String)`	Calcula o desvio padrão da propriedade Temperatura por intervalo. `null` Evita valores.

Para um tipo de variável de agregação , essas funções podem ser combinadas na expressão de agregação. Por exemplo: max($event.Temperature.Long) - min($event.Temperature.Long).

Sintaxe

Esta seção descreve os principais conceitos de sintaxe e operadores de consulta concatenados para expressões de formulário.

Literais com suporte

Observação

Os literais abaixo são usados para formar expressões, consulte o artigo Tipos de dados com suporte para obter a lista completa de tipos de dados.

Tipo primitivo	Literais
Bool	`TRUE`, `FALSE`
DateTime	`dt'2016-10-08T03:22:55.3031599Z'`
Double	`1.23`, `1.0`
Long	`1`, `6`
Cadeia de caracteres	`'abc'`
TimeSpan	`ts'P1Y2M3DT4M5.67S'`
Nulo	`NULL`

Tipos de operando com suporte

Operação	Tipos com suporte	Observações
<, >, <, >	Double, Long, DateTime, TimeSpan
=, =, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> é equivalente a !=
+, -, *, /	Double, Long, DateTime, TimeSpan

Para expressões de comparação (<, >, <=, >=, =, !=), os operandos podem ser NULL ou ser do mesmo tipo. Em cada expressão de predicado, os tipos de operandos LHS (lado esquerdo) e RHS (lado direito) são validados para corresponder. Erros ocorrem quando tipos de LHS e RHS não concordam ou uma operação não é permitida em tipos específicos.

Observação

O tipo de cadeia de caracteres não permite valor nulo no Warm Store:

A comparação de Cadeia de Caracteres com NULL e cadeia de caracteres vazia ('') se comporta da mesma maneira: $event.p1.String = NULL é equivalente a $event.p1.String = ''.
A API pode retornar valores NULL mesmo se os eventos originais contiverem cadeias de caracteres vazias.

No futuro, o mesmo comportamento será no Cold Store.

Não use a dependência de valores NULL em colunas String e trate-os da mesma maneira que cadeias de caracteres vazias.

Um tipo marcar é aplicado:
- Qualquer tipo de propriedade é aceito em relação a um NULL literal.
- Os tipos de LHS e RHS devem corresponder.

Aqui estão exemplos das propriedades p1 e p2 do tipo String, propriedade p3 do tipo Double e uma propriedade aninhada armazenada como p4.p5 do tipo Double:

Filtrar	É válido?	Observações
`$event.p1.String = 'abc'`	Sim
`$event.p1.String = $event.p2.String`	Sim
`$event.p1.String = NULL`	Sim	`NULL` corresponde a qualquer tipo do lado esquerdo.
`$event.p3.Double = 'abc'`	Não	Tipos incompatíveis.
`$event.p3.Double = $event.p1.String`	Não	Tipos incompatíveis.
`$event.p1 = 'abc'`	Não	Tipos incompatíveis.
`$event.p1 = 1`	Não	Tipos incompatíveis.
`$event.p1 = true`	Não	Tipos incompatíveis.
`$event.p1 = NULL`	Sim	`p1` é o único token usado. Interpretado como `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Sim	`['p1']` é o único token usado. Interpretado como `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	Não	Sintaxe de referência de propriedade inválida. Um tipo deve ser especificado no LHS de comparação.
`$event.p4.p5.Double = 0.0`	Sim

Funções escalares com suporte

Veja abaixo a lista de funções escalares por categorias:

Funções de conversão

Nome da função	Assinatura	Exemplo	Observações
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Converte os argumentos em Double.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Converte os argumentos em Long.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Converte argumentos em Cadeia de caracteres.

Funções matemáticas

Nome da função	Assinatura	Exemplo	Observações
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Arredonda um número flutuante de precisão dupla para o integral mais próximo.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Retorna o menor valor integral que é maior ou igual ao número de ponto flutuante de precisão dupla.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Retorna o maior valor integral que é menor ou igual ao número de ponto flutuante de precisão dupla.

Funções trigonométricas

Nome da função	Assinatura	Exemplo	Observações
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Retorna o Cosseno do ângulo especificado em radianos.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Retorna o seno do ângulo especificado em radianos.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Retorna a Tangente do ângulo especificado em radianos.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Retorna o ângulo em radianos cujo Cosseno é o número especificado.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Retorna o ângulo em radianos cujo seno é o número especificado.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Retorna o ângulo em radianos cuja Tangente é o número especificado.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Retorna o ângulo em radianos cuja Tangente é o quociente de dois números especificados.

Funções logarítmicas

Nome da função	Assinatura	Exemplo	Observações
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Retorna o logaritmo natural de um número especificado.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Retorna o logaritmo de base 2 de um número especificado.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Retorna o logaritmo de base 10 de um número especificado.

Funções de data e hora

Nome da função	Assinatura	Exemplo	Observações
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Retorna o mês do ano como um numérico para o DateTime fornecido.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Retorna o dia do mês como um numérico para o DateTime fornecido.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Retorna a hora do dia como um numérico para o DateTime fornecido.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Retorna a hora atual no formato UTC.

Funções de cadeia de caracteres

Nome da função	Assinatura	Exemplo	Observações
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Retorna a cadeia de caracteres de entrada convertida em maiúsculas.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Retorna a cadeia de caracteres de entrada convertida em minúsculas.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Retorna o número dos caracteres no argumento de cadeia de caracteres.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Concatena duas cadeias de caracteres de entrada especificadas.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Recupera uma subcadeia de caracteres desta instância.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Retorna uma nova cadeia de caracteres removendo todos os caracteres de espaço em branco à esquerda e à direita da cadeia de caracteres de entrada.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Retorna a primeira ocorrência da cadeia de caracteres especificada dentro da cadeia de caracteres original, com base na indexação zero.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Retorna uma cadeia de caracteres em que todas as ocorrências da cadeia de caracteres de pesquisa são substituídas pela cadeia de caracteres de substituição.

Outras funções

Nome da função	Assinatura	Exemplo	Observações
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Retorna o primeiro valor não nulo na lista de argumentos. Aceita no mínimo 2 e no máximo 64 argumentos, mas todos eles devem ser do mesmo tipo de dados.
`iff`	`String, Long, Double, Bool iff (predicate: bool, ifTrue: String, Long, Double, Bool, ifFalse: String, Long, Double, Bool)`	`iff ($event.value.Double > 100, 'Good', 'Bad')`	Retorna o segundo ou o terceiro argumento dependendo se o predicado foi resolvido como true (retorna o segundo argumento) ou false (retorna o terceiro argumento). O predicado deve ser uma expressão booliana e o segundo e o terceiro argumentos devem ser do mesmo tipo.

Confira também

Para obter mais informações sobre o registro de aplicativo e o modelo de programação do Azure Active Directory, consulte Azure Active Directory para desenvolvedores.
Para saber mais sobre os parâmetros de solicitação e autenticação, leia Autenticação e autorização.
As ferramentas que auxiliam no teste de solicitações e respostas HTTP incluem:
Fiddler. Esse proxy de depuração da Web gratuito pode interceptar suas solicitações REST, para que você possa diagnosticar as mensagens de solicitação e resposta HTTP.
JWT.io. Você pode usar essa ferramenta para despejar rapidamente as declarações em seu token de portador e, em seguida, validar seu conteúdo.
O Postman. Essa é uma ferramenta gratuita de teste de solicitação HTTP e resposta para depuração de APIs REST.
Saiba mais sobre Azure Time Series Insights Gen2 examinando a documentação do Gen2.