sintaxe de consulta do Azure Time Series Insights Gen1

Cuidado

Esse é um artigo do Gen1.

Este artigo descreve o formato e a sintaxe da solicitação de consulta para a API de Consulta do Azure Time Series Insights Gen1.

Resumo

Importante

• As solicitações de consulta devem estar no formato JSON.
• As cargas de solicitação HTTP feitas à API de Consulta devem estar em conformidade com o formato especificado neste artigo.

A linguagem é subdividida nos seguintes elementos:

• Expressões escalares, que produzem valores escalares. As expressões escalares incluem expressões de cadeia de caracteres de predicado, expressões de comparação e expressões aritméticas.
• Funções escalares, que retornam valores escalares.
• Expressões de agregação, que são usadas para particionar coleções de eventos e medidas de computação sobre as partições.
• Cláusulas, que formam os componentes constituintes de consultas JSON ou uma parte de uma expressão.

Modelo de dados

A API de Consulta do Azure Time Series Insights Gen1 opera em dados armazenados como eventos individuais em um ambiente. Cada evento é um conjunto de pares de nome e valor da propriedade.

Propriedades do evento

As propriedades do evento podem ser de um dos seguintes tipos primitivos: Bool, DateTime, Double ou String. Todos os tipos primitivos são anuláveis.

Observação

Formatos de origem de evento personalizados podem dar suporte a um conjunto maior de tipos de valor. Azure Time Series Insights Gen1 infere o tipo primitivo mais próximo e, em seguida, converte tipos personalizados neles na entrada.

Todos os eventos têm as seguintes propriedades internas com um nome e um tipo predefinidos:

Nome da propriedade	Tipo de propriedade	Definição
$ts	DateTime	Carimbo de data/hora do evento
$esn	Cadeia de caracteres	Nome da origem do evento

• Carimbo de data/hora do evento

  Por padrão, um valor de carimbo de data/hora do evento é fornecido pela origem do evento. Por exemplo, eventos provenientes de um hub IoT teriam seu tempo enfileirado como um carimbo de data/hora.

  Em vez disso, os clientes podem modificar esse comportamento configurando outra propriedade de evento. As propriedades de carimbo de data/hora personalizadas podem ser especificadas em hubs de eventos e hubs IoT.

• Nome da origem do evento

  O nome da origem do evento é o nome exibido para a origem do evento do qual Azure Time Series Insights Gen1 recebeu o evento. Os nomes de origem do evento são associados a um evento específico no momento da entrada.

  Importante

  • Os nomes de origem do evento permanecem inalterados durante o tempo de vida do evento.
  • Se o nome de uma origem do evento for modificado, os eventos existentes levarão o nome de origem do evento antigo. Novos eventos levarão o novo nome de origem do evento.

Tipos de evento

As propriedades de evento personalizado são identificadas e referenciadas exclusivamente em expressões de consulta por nome e tipo. Um evento pode ter mais de uma propriedade com o mesmo nome e tipos diferentes. Propriedades com o mesmo nome, mas tipos diferentes podem resultar da divisão de tipo de entrada.

Um valor de propriedade de evento do tipo String pode ser armazenado como uma propriedade com um tipo diferente nos seguintes casos:

• Se um valor String for um valor Double válido, ele será armazenado como Double e String.
• Se um valor String for um valor DateTime válido, ele será armazenado apenas como DateTime .

A API de Consulta converte literais de Cadeias de Caracteres vazias ("") null em na saída.

Azure Time Series Insights Gen1 tem suporte limitado para os seguintes valores dentro do tipo Double: Double.NaN, Double.PositiveInfinitye Double.NegativeInfinity. Esses valores são convertidos em durante a null entrada, mas se a avaliação da consulta produzir um desses valores, o valor será avaliado e serializado como uma Cadeia de caracteres em resposta.

Você pode passar esses valores como Cadeias de caracteres para entrada, portanto, em expressões de consulta, esses valores também devem ser passados como Cadeias de caracteres.

Esquemas de evento descrevem as propriedades de um evento. Um esquema de evento contém o nome de uma origem do evento e o conjunto ordenado de propriedades para o evento. Eventos diferentes podem ter esquemas diferentes ou compartilhar o mesmo esquema.

Expressões escalares

Expressões escalares produzem valores escalares. As expressões escalares são divididas nos seguintes tipos:

• Expressões constantes
• Expressões de referência de propriedade
• Expressões de comparação
• Expressões aritméticas
• Expressões de cadeia de caracteres de predicado

Expressões constantes

Você representa expressões constantes usando os literais a seguir para cada um dos tipos primitivos:

Tipo primitivo	Representação JSON	Exemplo de JSON	Observações
Bool	Como um tipo booliano JSON	true, false
DateTime	Como um objeto aninhado com uma única propriedade dateTime no formato yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFKISO 8601 .	{"dateTime":"2016-08-01T00:00:00.000Z"}
Double	Um número JSON convertido no intervalo Duplo.	1.23e45, 123	Estouros duplos gerarão um erro.
Cadeia de caracteres	Um tipo de cadeia de caracteres JSON	"abc"
TimeSpan	Como um objeto aninhado com a propriedade timeSpan única no formato ISO 8601 : P[n]Y[n]M[n]DT[n]H[n]M[n]S.	{"timeSpan":"P1Y2M3DT4M5.67S"}

Tipos primitivos anuláveis

Tipos de dados primitivos permitem valor nulo. null Os valores para tipos primitivos são expressos em JSON da seguinte maneira:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Expressões de referência de propriedade

Você usa uma expressão de referência de propriedade para acessar os valores de propriedades não internas de um evento. As propriedades não internas incluem qualquer propriedade personalizada além das padrão que são automaticamente contidas em um esquema de evento.

O tipo de resultado de uma expressão de referência de propriedade é o tipo primitivo da propriedade. As propriedades no esquema de evento são identificadas exclusivamente por nome e tipo, e a expressão de referência requer que ambas sejam especificadas.

• Exemplos de JSON:

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

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

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

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

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

Uma expressão de referência de propriedade interna é usada para acessar propriedades internas de um evento. As propriedades internas são apenas aquelas que são definidas automaticamente em um esquema de evento.

O tipo de resultado de uma expressão de referência de propriedade interna é o tipo primitivo da propriedade . As propriedades internas são referenciadas apenas pelo nome; Portanto, nenhum tipo é necessário na expressão de referência:

{ "builtInProperty": "$esn" }

Expressões de comparação

Há suporte para as seguintes expressões de comparação boolianas :

Nome da propriedade em JSON	Descrição
eq	Igual
Em	In (igual a any)
phrase	Contém frase
startsWith	Começa com
endsWith	Termina com frase
regex	Corresponde à expressão regular
lt	Menor que
lte	Inferior ou igual
gt	Maior que
Gte	Maior ou igual

Importante

• Todas as expressões de comparação pegam os tipos primitivos de argumentos à esquerda e à direita e retornam um valor booliano que representa o resultado da comparação.
• Os dois tipos de argumentos à esquerda e à direita em comparações devem corresponder.
• Não há suporte para todos os tipos implicitamente convertidos em si mesmos, e não há suporte para conversões explícitas.

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

• Exemplos de 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"
     }
  }
  

A tabela a seguir mostra os tipos de argumentos com suporte para cada uma das expressões de comparação:

Tipo de argumento	Operação de comparação com suporte
Bool	eq, in
DateTime	eq, in, lt, lte, gt, gte
Double	eq, in, lt, lte, gt, gte
Cadeia de caracteres	eq, in, phrase, startsWith, endsWith, regex
TimeSpan	eq, in, lt, lte, gt, gte

O literal NULL só pode ser usado com os seguintes operadores de comparação: eq ou in.

• O operador eq resultará em true se ambos os lados forem null valores. Caso contrário, o operador resultará em false.
• Para outras operações, o erro é gerado para o literal NULL e o comportamento é indefinido para propriedades de valor nulo (qualquer operação de comparação que resulte em false).
• Um null valor precede valores não nulos em ordenações de classificação (por exemplo, se a classificação por uma propriedade for aplicada para retornar uma lista de eventos).

Azure Time Series Insights Gen1 dá suporte às seguintes expressões lógicas boolianas:

Nome da propriedade em JSON	Descrição
and	Usa um conjunto não vazio de argumentos boolianos e retorna true se todos eles forem avaliados como true.
or	Usa um conjunto não vazio de argumentos boolianos e retorna true se algum deles for avaliado truecomo .
not	Usa um único argumento booliano e retorna seu valor negado.

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

A propriedade stringComparison é opcional. Por padrão, seu valor é OrdinalIgnoreCase, o que faz com que o uso de maiúsculas e minúsculas da frase seja ignorado em comparações.

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

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

Expressões aritméticas

Azure Time Series Insights Gen1 dá suporte às seguintes expressões aritméticas:

Nome da propriedade em JSON	Descrição
adicionar	Adição
sub	Subtração
Mult	Multiplicação
div	Divisão

Todas as expressões aritméticas pegam os argumentos esquerdo e direito de tipos primitivos e retornam um valor que representa o resultado da operação.

Não há suporte para todos os tipos implicitamente convertidos em si mesmos, e não há suporte para conversões explícitas.

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

A tabela a seguir mostra os tipos de argumentos com suporte para cada uma das expressões aritméticas:

Operação	Tipo esquerdo	Tipo à direita	Tipo de resultado
adicionar	Double	Double	Double
adicionar	TimeSpan	TimeSpan	TimeSpan
adicionar	DateTime	TimeSpan	DateTime
adicionar	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

Expressões de cadeia de caracteres de predicado

Expressões de cadeia de caracteres de predicado booliano contêm predicados boolianos que são representados como expressões legíveis por humanos chamadas cadeias de caracteres de predicado.

Exemplos de cadeias de caracteres de predicado:

Cadeia de caracteres de predicado	Descrição
Description HAS 'hello world'	true para eventos que contêm a frase hello world na propriedade Description em todas as fontes de evento
'hello world'	true para eventos que contêm a frase hello world
startsWith(Status, 'go')	true para eventos com Status começando com go
endsWith(Status, 'oD')	true para eventos com Status terminando com od
startsWith_cs(Status, 'Go')	true para eventos com Status começando com Go
endsWith_cs(Status, 'od')	true para eventos com Status começando com od
matchesRegex(s, '^G*')	true para eventos com Status que correspondem à expressão regular ^G*
PointValue.Double = 3.14	true para eventos com PointValue duplo igual a 3.14
Status IN ('Good','Bad')	true para eventos com Status que contém Good ou Bad
PointValue > 3.14 AND Status.String = 'Good'	true para eventos com PointValue maior que 3.14 e status de cadeia de caracteres de Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'	true para eventos com PointValue maior que 3.14 e Status de Good ou Bad e Descrição não contendo a frase hello world

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

A expressão na cadeia de caracteres de predicado é avaliada em uma expressão booliana JSON. Ele deve estar em conformidade com a seguinte gramática (simplificada):

Expressão booliana JSON	Formulário 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 tipos de dados primitivos Gen1 têm suporte em expressões de cadeia de caracteres de predicado.

Ao contrário das expressões de referência de propriedade JSON, um tipo para uma propriedade pode ser omitido; nesse caso, um tipo é inferido automaticamente.

Literais com suporte

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

Tipos de operando com suporte

Operação	Tipos com suporte	Observações
<, >, <, >	Double, DateTime, TimeSpan
=, =, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> é equivalente a !=
+, -, *, /	Double, DateTime, TimeSpan
IN	String, Bool, Double, DateTime, TimeSpan, NULL	Todos os operandos devem ser do mesmo tipo ou ser uma constante NULL. Vários NULLs são equivalentes a um único NULL.
HAS	Cadeia de caracteres	Apenas os literais de cadeia de caracteres de constante são permitidos no lado direito. Cadeia de caracteres vazia e NULL não são permitidos.

Para predicados de comparação (<, >, <=, >=, =, !=) e o operando de predicado IN podem ser NULL ou ter um único tipo.

Para expressões com um predicado HAS , o literal constante no lado direito do operando HAS pode ser expandido em vários tipos. Além disso, o literal constante no lado direito do operando HAS é analisado em um valor Bool, Double, DateTime ou TimeSpan . Para cada valor analisado com êxito, um predicado com o = operador é criado. Esses predicados e o predicado HAS original são unidos em um predicado OR . Por exemplo, uma cadeia de caracteres de predicado p1 HAS '1.0' será equivalente a p1.String HAS '1.0' OR p1.Double = 1.0, se existirem propriedades p1 com tipos String e Double .

Verificação de tipo

As expressões de predicado são verificadas por tipo e validadas para garantir que os tipos à direita e à esquerda dentro delas correspondam.

Importante

• Quando as constantes à esquerda e à direita de um operando não correspondem, um erro é gerado.
• Um erro também será gerado se uma operação não for permitida em ou entre tipos específicos.

• Se um tipo for especificado para a propriedade , um tipo marcar será aplicado:

  • Qualquer tipo de propriedade é aceito em um literal NULL .

  • Caso contrário, os tipos do lado esquerdo e do lado direito devem corresponder.

    Exemplos das propriedades p1 e p2 do tipo String e da propriedade p3 do tipo Double são exibidos na tabela a seguir:

    Cadeia de caracteres de predicado	É válido?	Observações
    p1.String = 'abc'	Sim
    p1.String = p2.String	Yes
    p1.String = NULL	Yes	NULL corresponde a qualquer tipo do lado esquerdo.
    p3.Double = 'abc'	Não	Tipos incompatíveis.
    p3.Double = p1.String	Não	Tipos incompatíveis.
    p1.String HAS 'abc'	Yes
    p3.Double HAS '1.0'	Yes	O literal de cadeia de caracteres foi analisado com êxito para um valor Double .

• Se um tipo for omitido para a propriedade, mas um nome for especificado, as seguintes etapas serão executadas:

  1. Todas as propriedades com um nome e tipos especificados são tomadas.
  2. Operandos do lado esquerdo e do lado direito são agrupados em pares por tipo.
  3. Os pares são concatenados usando operações AND .

  • Exemplos das propriedades p1 e p2 dos tipos String e Double e alguns de seus equivalentes são exibidos na tabela a seguir:

    Cadeia de caracteres de predicado	Cadeia de caracteres de predicado de tipo forte equivalente	Observações
    p1 = 'abc'	p1.String = 'abc'
    p1 = true		Nenhuma propriedade p1 do tipo Bool, portanto, um erro de propriedade ausente é emitido.
    p1 = NULL	p1.String = NULL AND p1.Double = NULL	Para NULL o lado direito, supõe-se que todas as propriedades correspondentes devem ser NULL.
    p1 != NULL	p1.String != NULL OR p1.Double != NULL	Essa é uma inversão da expressão anterior.
    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	Isso é o equivalente a p1 = NULL.
    p1 HAS '1.0'	p1.String HAS '1.0' OR p1.Double = 1.0	O literal da cadeia de caracteres foi analisado com êxito para um valor Double válido.
    p1 HAS 'true'	p1.String HAS 'true'	O literal da cadeia de caracteres foi analisado com êxito para Bool, mas não p1. A propriedade Bool existe.
    p1 = p2	p1.String = p2.String AND p1.Double = p2.Double
    p1 != p2	p1.String != p2.String OR p1.Double != p2.Double	Essa é uma inversão da expressão anterior.

• O nome e o tipo da propriedade podem ser omitidos para uma propriedade do lado esquerdo se o tipo de propriedade do lado direito estiver bem definido. Isso é verdade sempre que o lado direito tem literais constantes e não contém apenas um NULL literal.

  • Esse cenário é uma generalização da pesquisa de texto completo que usa o operando HAS .

  • Todas as propriedades que correspondem ao tipo do lado direito são obtidas e as expressões resultantes são concatenadas por meio de uma operação OR .

  • Exemplos da propriedade p1 dos tipos String e Double e da propriedade p2 dos tipos String e DateTime são exibidos na tabela a seguir:

    Cadeia de caracteres de predicado	Cadeia de caracteres de predicado de tipo forte equivalente	Observações
    = 'abc'	p1.String = 'abc' OR p2.String = 'abc'
    != 'abc'	p1.String != 'abc' AND p2.String != 'abc'	Inversão da expressão anterior
    = 1.0	p1.Double = 1.0
    = dt'2000-01-02T03:04:05'	p2.DateTime = dt'2000-01-02T03:04:05'
    = true		Erro. Nenhuma propriedade Bool existe, portanto, um erro de propriedade ausente é emitido.
    = NULL		Erro. Não é permitido omitir o nome da propriedade para NULL o lado direito.
    IN (NULL)		O mesmo que o erro anterior.
    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'	Não há nenhuma propriedade com o tipo Bool.

• Se o operador for omitido junto com um nome de propriedade, a HAS operação será assumida.

Funções escalares

As funções escalares retornam valores escalares.

Funções nativas

As funções escalares compatíveis com o Azure Time Series Insights Gen1 incluem:

Nome da função	Valor retornado	Argumentos	Exemplo	Observações
utcNow	DateTime	Nenhum	utcNow()	Retorna a hora atual no formato UTC. O nome da função diferencia maiúsculas de minúsculas.

A função UTC agora retorna um valor DateTime , que contém a hora atual no formato UTC. Ele não aceita argumentos.

Expressões de agregação

Expressões de agregação são usadas para particionar coleções de eventos e medidas de computação nas partições. As expressões de agregação são divididas nos seguintes tipos:

• Expressões de dimensão
• Expressões de valores exclusivos
• Expressões de histograma de data
• Medir expressões

Expressões de dimensão

Você usa expressões de dimensão dentro de uma cláusula aggregates para particionar um conjunto de eventos e atribuir uma chave escalar a cada partição.

Tipos de expressão de dimensão:

Nome da propriedade em JSON	Descrição	Exemplo
uniqueValues	Os valores de dimensão no resultado são valores exatos de uma determinada propriedade.
dateHistogram	Os valores de dimensão no resultado são intervalos de tempo de uma determinada propriedade.	O histograma de data do carimbo de data/hora pode resultar em intervalos de 10 horas para um intervalo de pesquisa de 10 horas.
numericHistogram	Os valores de dimensão no resultado são intervalos de valores em uma determinada propriedade.	O histograma numérico de temperatura pode resultar em um retorno de 10 intervalos de graus.

Azure Time Series Insights Gen1 restringe a cardinalidade máxima ou o tamanho máximo da rede de uma consulta de agregação de entrada a 150.000 células. Para calcular a cardinalidade de uma consulta de agregação, multiplique os tamanhos de todas as dimensões na consulta. Desde que o produto seja menor que 150.000, a consulta é aceita para execução. Se o produto for igual ou menor que 150.000, a consulta será rejeitada.

Especifique o tamanho máximo de uma dimensão produzida por uniqueValues e numericHistogram usando a cláusula take . Em dateHistogram, o tamanho é calculado dividindo o intervalo de pesquisa pelo tamanho do intervalo dateHistogram , que você especifica usando a cláusula breaks .

Por exemplo, uma consulta de agregação tem o intervalo de pesquisa definido de "2017-11-15T16:00:00.000Z" para "2017-11-15T19:00:00.000Z" = 3 horas. Se a consulta incluir dateHistogram com a cláusula breaks , definida como 1 minuto (dimensão 1) e uniqueValues sobre a propriedade XYZ, o tamanho da dimensão dateHistogram será 3x60=180. Esse resultado significa que uniqueValues pode levar até 150.000/180 = total de 833 itens.

Expressões de valores exclusivos

Você usa uma expressão de valores exclusivos para agrupar um conjunto de eventos pelos valores de uma propriedade de evento especificada.

A avaliação dessa expressão JSON resulta em até 100 registros, que são agrupados pela sensorId propriedade String.

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

Expressões de histograma de data

Você usa uma expressão de histograma de data para agrupar valores de propriedade DateTime em buckets de um tamanho especificado.

Uma avaliação dessa expressão JSON resulta em um conjunto de registros timestamp arredondados de modo que cada valor tenha segundos zerados.

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

Expressões de histograma numérico

Você usa uma expressão de histograma numérica para agrupar valores de propriedade Double em um número especificado de buckets.

Uma avaliação dessa expressão JSON resulta em 10 registros, portanto, o intervalo entre os valores mínimo e máximo da propriedade p1 é dividido em 10 buckets.

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

Expressões de medida

Você usa expressões de medida dentro de cláusulas de agregações para calcular um valor escalar em um conjunto de eventos. Por exemplo, uma expressão de medida é o cálculo do valor máximo medido por um sensor de temperatura nas últimas 24 horas.

Você usa uma expressão de contagem para calcular o número de eventos em um bucket correspondente.

{ "count": {} }

Você usa expressões min, max, avg e sum para calcular o mínimo, o máximo, a média e a soma dos valores de uma propriedade especificada em um bucket correspondente.

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

Com as expressões de primeira e última medida, você pode obter o valor de uma propriedade especificada A que corresponde ao valor mínimo ou máximo da propriedade B.

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

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

A cláusula orderBy é opcional e usa como padrão a propriedade Timestamp$ts. A entrada pode ser de qualquer tipo. A cláusula orderBy dá suporte apenas aos tipos Double e DateTime .

Se a propriedade B for um tipo DateTime , você obterá o valor mais recente ou o valor mais antigo da propriedade A.

Você pode usar primeira e última expressões para ajudar a entender o valor mais antigo ou mais recente de uma propriedade específica. Por exemplo, se você tiver uma propriedade chamada deviceID e quiser entender o mais recente deviceID que enviou um evento, last será o operador de expressão mais eficiente a ser usado para identificar essas informações.

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

Outro exemplo é usar o último para localizar o último local relatado de um objeto específico, como um navio, veículo ou outro objeto em movimento.

Para ilustrar uma consulta que produz o último local conhecido dos navios em uma frota, você pode criar uma consulta semelhante à seguinte:

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

Outro exemplo é usar primeiro para encontrar um dispositivo que relata a menor pressão para cada planta:

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

Suporte a dimensões e tipos de medida

Aqui estão as expressões de medida e dimensão com suporte, com base no tipo de propriedade:

Tipo de propriedade	Expressões de dimensão com suporte	Expressões de medida com suporte
Bool	"uniqueValues"	"first" (entrada), "last" (entrada)
DateTime	"uniqueValues", "dateHistogram"	"min", "max", "first" (orderBy, input), "last” (orderBy, input)
Double	"uniqueValues", "numericHistogram"	"sum", "avg", "min", "max", "first" (orderBy, input), "last” (orderBy, input)
Cadeia de caracteres	"uniqueValues"	"first" (entrada), "last" (entrada)

Cláusulas

As cláusulas formam componentes constituintes de consultas JSON ou uma parte de uma expressão. As cláusulas são divididas nos seguintes tipos:

• Cláusulas de intervalo de pesquisa
• Cláusulas de predicado
• Limitar cláusulas superiores
• Limitar cláusulas take
• Limitar cláusulas de exemplo
• Cláusulas Breaks
• Cláusulas aggregates

Cláusulas de intervalo de pesquisa

Você usa uma cláusula de intervalo de pesquisa para filtrar uma propriedade timestamp interna de um evento para um determinado intervalo. O início do intervalo é inclusivo. O final do intervalo é exclusivo.

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

As propriedades de e para na cláusula search span (searchSpan) devem ser expressões válidas do tipo de resultado DateTime . Essas expressões são avaliadas antes da execução da consulta, o que significa que elas não devem conter nenhuma referência de propriedade.

Cláusulas de predicado

Use uma cláusula de predicado para filtrar eventos que satisfaçam o predicado. Ele deve ser resolvido em uma expressão booliana .

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

Filtrar eventos significa executar um predicado representado por uma expressão booliana em cada evento no ambiente. A execução de uma expressão em um evento retornará true se o evento precisar ser incluído em outras operações. Ele retornará false se o evento precisar ser omitido do processamento adicional.

Observação

Os eventos são sempre filtrados pelo intervalo de pesquisa, além de qualquer filtragem especificada em uma expressão de predicado.

Limitar cláusulas superiores

Você usa uma cláusula *limit top para obter um número especificado de valores em ordem crescente ou decrescente. O número de valores é limitado de acordo com a contagem especificada.

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

Limitar cláusulas take

Você pode usar uma cláusula limit take como uma maneira rápida de obter um conjunto de valores em nenhuma ordem específica. O número de valores retornados é limitado pela entrada especificada.

{ "take": 10 }

Limitar cláusulas de exemplo

Você usa uma cláusula de exemplo *limit para obter uma amostra estatisticamente representativa de um conjunto de valores. O número de valores retornados é limitado pela entrada especificada.

{ "sample": 10 }

Cláusulas Breaks

Use uma cláusula *breaks em expressões de histograma para especificar como um intervalo deve ser dividido.

Para histogramas de data, você deve especificar o tamanho dos limites de intervalo e intervalo de datetime. Você faz isso, a menos que o histograma seja baseado em uma propriedade timestamp interna em que os limites são determinados com base no intervalo de pesquisa:

• Os limites de intervalo são opcionais e podem ser usados. Por exemplo, você pode usá-los quando forem determinados com base em um intervalo de pesquisa se os limites de intervalo forem omitidos.
• Para histogramas numéricos, você deve especificar o número de quebras. Você determina limites de intervalo com base nos valores mínimo e máximo de uma propriedade.

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

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

Cláusulas aggregates

Você usa uma cláusula aggregates para particionar um conjunto de eventos por uma determinada propriedade enquanto está medindo os valores de outras propriedades de evento.

As medidas são avaliadas em cada partição produzida pela expressão de dimensão.

• O exemplo JSON a seguir calcula as temperaturas média, mínima e máxima por ID do sensor.

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

  Observação

  Uma cláusula aggregates é uma matriz que permite especificar mais de uma agregação no nível superior.

• O exemplo JSON a seguir calcula a temperatura média por cidade e por fabricante de forma independente:

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

  Observação

  • Atualmente, não há suporte para ter mais de um elemento em uma matriz de agregações.
  • No entanto, uma definição de agregação pode incluir uma matriz aninhada que especifica uma rede multidimensional mais flexível.

• O exemplo JSON a seguir calcula a temperatura média por ID do sensor, por 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"
                }
              }
            }
          ]
        }
      }
    ]
  }
  

Confira também

• Para obter mais informações sobre as APIs do Azure Time Series Insights Gen1, consulte APIs gen1.

• Para saber mais sobre os parâmetros de solicitação e autenticação, consulte Autenticação e autorização.

• Saiba mais sobre Azure Time Series Insights Gen1 examinando a documentação do Gen1.