sintaxe de consulta Azure Time Series Insights Gen1

Artigo
08/05/2023

Atenção

Este é um artigo da Gen1.

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

Resumo

Importante

Os pedidos de consulta têm de estar no formato JSON.
Os payloads de pedido HTTP efetuados à API de Consulta devem estar em conformidade com o formato especificado neste artigo.

O idioma é subdividido nos seguintes elementos:

Expressões escalares, que produzem valores escalares. As expressões escalares incluem expressões de cadeia de carateres predicados, expressões de comparação e expressões aritméticas.
Funções escalares, que devolvem valores escalares.
Expressões agregadas, que são utilizadas para coleções de partições de eventos e medidas de computação sobre as partições.
Cláusulas, que formam os componentes constituintes das consultas JSON ou uma parte de uma expressão.

Modelo de dados

A API de Consulta Azure Time Series Insights Gen1 opera em dados armazenados como eventos individuais num ambiente. Cada evento é um conjunto de pares de nomes de propriedades e valores .

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 nublaveis.

Nota

Os formatos de origem de eventos personalizados podem suportar um conjunto maior de tipos de valores. Azure Time Series Insights Gen1 infere o tipo primitivo mais próximo e, em seguida, lança-lhes tipos personalizados na entrada.

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

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

Carimbo de data/hora do evento

Por predefinição, um valor de carimbo de data/hora do evento é fornecido pela origem do evento. Por exemplo, os eventos provenientes de um hub IoT teriam o seu tempo em fila como carimbo de data/hora.

Em vez disso, os clientes podem modificar este comportamento ao configurar 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 de evento

O nome da origem do evento é o nome apresentado para a origem do evento a partir da qual Azure Time Series Insights Gen1 recebeu o evento. Os nomes das origens de eventos estão associados a um evento específico no momento da entrada.
Importante
- Os nomes das origens de eventos permanecem inalterados durante a duração do evento.
- Se o nome de uma origem de eventos for modificado, os eventos existentes têm o nome de origem de evento antigo. Os novos eventos terão o novo nome de origem de eventos.

Tipos de evento

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

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

Se um valor de Cadeia for um valor Duplo válido, é armazenado como Duplo e Cadeia.
Se um valor de Cadeia for um valor DateTime válido, é armazenado apenas como DateTime .

A API de Consulta converte literais de Cadeias ("") null vazios em no resultado.

Azure Time Series Insights Gen1 tem suporte limitado para os seguintes valores no Tipo duplo: Double.NaN, Double.PositiveInfinitye Double.NegativeInfinity. Estes valores são convertidos em durante a null entrada, mas se a avaliação de consulta produzir um destes valores, o valor é avaliado e serializado como uma Cadeia em resposta.

Pode transmitir estes valores como Cadeias para entrada, pelo que, nas expressões de consulta, estes valores também devem ser transmitidos como Cadeias.

Os esquemas de eventos descrevem as propriedades de um evento. Um esquema de evento contém o nome de uma origem de evento e o conjunto ordenado de propriedades do evento. Diferentes eventos podem ter esquemas diferentes ou partilhar o mesmo esquema.

Expressões escalares

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

Expressões constantes
Expressões de referência de propriedade
Expressões de comparação
Expressões aritméticas
Predicar expressões de cadeia

Expressões constantes

Representa expressões constantes ao utilizar os seguintes literais para cada um dos tipos primitivos:

Tipo primitivo	Representação JSON	Exemplo JSON	Notas
Bool	Como um tipo booleano JSON	`true`, `false`
DateTime	Como um objeto aninhado com uma propriedade dateTime única no formato `yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK`ISO 8601 .	`{"dateTime":"2016-08-01T00:00:00.000Z"}`
Duplo	Um número JSON lançado para o intervalo Duplo.	`1.23e45`, `123`	Os excessos duplos gerarão um erro.
String	Um tipo de cadeia JSON	`"abc"`
TimeSpan	Como um objeto aninhado com uma única propriedade timeSpan no formato ISO 8601 : `P[n]Y[n]M[n]DT[n]H[n]M[n]S`.	`{"timeSpan":"P1Y2M3DT4M5.67S"}`

Tipos primitivos anuláveis

Os tipos de dados primitivos são anuláveis. null os valores para tipos primitivos são expressos em JSON da seguinte forma:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Expressões de referência de propriedade

Utilize uma expressão de referência de propriedade para aceder aos valores de propriedades não incorporadas de um evento. As propriedades não incorporadas incluem qualquer propriedade personalizada para além das predefinidas que estão automaticamente contidas num esquema de eventos.

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

Exemplos 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 incorporada é utilizada para aceder a propriedades incorporadas de um evento. As propriedades incorporadas são apenas as propriedades que são definidas automaticamente num esquema de eventos.

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

{ "builtInProperty": "$esn" }

Expressões de comparação

São suportadas as seguintes expressões de comparação booleana :

Nome da propriedade em JSON	Description
eq	Igual
em	Em (igual a qualquer)
expressão	Contém expressão
startsWith	Starts with
endsWith	Termina com expressão
regex	Corresponde à expressão normal
lt	Menor que
lte	Menor ou igual a
gt	Maior que
gte	Maior ou igual a

Importante

Todas as expressões de comparação assumem os tipos primitivos dos argumentos esquerdo e direito e devolvem um valor booleano que representa o resultado da comparação.
Ambos os tipos de argumentos esquerdo e direito em comparações devem corresponder.
Todos os tipos lançados implicitamente apenas para si mesmos e os moldes explícitos não são suportados.

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

Exemplos 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 seguinte mostra os tipos de argumentos suportados para cada uma das expressões de comparação:

Tipo de argumento	Operação de comparação suportada
Bool	eq, em
DateTime	eq, in, lt, lte, gt, gte
Duplo	eq, in, lt, lte, gt, gte
String	eq, em, expressão, startsWith, endsWith, regex
TimeSpan	eq, in, lt, lte, gt, gte

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

O operador eq resulta em true se ambos os lados forem null valores. Caso contrário, o operador resulta 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 ordenação (por exemplo, se a ordenação por uma propriedade for aplicada para devolver uma lista de eventos).

Azure Time Series Insights Gen1 suporta as seguintes expressões lógicas booleanas:

Nome da propriedade em JSON	Description
and	Utiliza um conjunto não vazio de argumentos booleanos e devolve `true` se todos forem avaliados como `true`.
ou	Utiliza um conjunto não vazio de argumentos booleanos e devolve `true` se algum deles for avaliado como `true`.
não	Pega num único argumento booleano e devolve o 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 predefinição, o respetivo valor é OrdinalIgnoreCase, o que faz com que o invólucro 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 suporta as seguintes expressões aritméticas:

Nome da propriedade em JSON	Description
adicionar	Adição
sub	Subtração
mult	Multiplicação
div	Divisão

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

Todos os tipos lançados implicitamente apenas para si mesmos e os moldes explícitos não são suportados.

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

A tabela seguinte mostra os tipos de argumentos suportados para cada uma das expressões aritméticas:

Operação	Tipo de esquerda	Tipo de direita	Tipo de resultado
adicionar	Duplo	Duplo	Duplo
adicionar	TimeSpan	TimeSpan	TimeSpan
adicionar	DateTime	TimeSpan	DateTime
adicionar	TimeSpan	DateTime	DateTime
sub	Duplo	Duplo	Duplo
sub	TimeSpan	TimeSpan	TimeSpan
sub	DateTime	DateTime	TimeSpan
sub	DateTime	TimeSpan	DateTime
mul	Duplo	Duplo	Duplo
div	Duplo	Duplo	Duplo

Predicar expressões de cadeia

As expressões de cadeia de predicado booleano contêm predicados booleanos representados como expressões legíveis por humanos chamadas cadeias de predicado.

Exemplos de cadeias de predicado:

Cadeia de predicado	Description
`Description HAS 'hello world'`	`true` para eventos que contêm a expressão `hello world` na propriedade Descrição em todas as origens de eventos
`'hello world'`	`true` para eventos que contêm a expressão `hello world`
`startsWith(Status, 'go')`	`true` para eventos com o Estado a começar por `go`
`endsWith(Status, 'oD')`	`true` para eventos com Estado a terminar com `od`
`startsWith_cs(Status, 'Go')`	`true` para eventos com o Estado a começar por `Go`
`endsWith_cs(Status, 'od')`	`true` para eventos com o Estado a começar por `od`
`matchesRegex(s, '^G*')`	`true` para eventos com Estado 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 o Estado que contém `Good` ou `Bad`
`PointValue > 3.14 AND Status.String = 'Good'`	`true` para eventos com PointValue maior que `3.14` e Estado da cadeia de carateres de `Good`
`[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'`	`true` para eventos com PointValue maior do que `3.14` e Estado de `Good` ou `Bad` e Descrição não contendo a expressão `hello world`

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

A expressão na cadeia de predicado é avaliada numa expressão booleana JSON. Deve estar em conformidade com a seguinte gramática (simplificada):

Expressão booleana 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 são suportados em expressões de cadeia de predicado.

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

Literais suportados

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

Tipos de operando suportados

Operação	Tipos suportados	Notas
<, >, <=, >=	Duplo, DateTime, TimeSpan
=, !=, <>	Cadeia, Bool, Duplo, DateTime, TimeSpan, NULL	<> é equivalente para !=
+, -, *, /	Duplo, DateTime, TimeSpan
IN	Cadeia, Bool, Duplo, DateTime, TimeSpan, NULL	Todos os operandos devem ter o mesmo tipo ou ser constante NULL . Vários NULLs são equivalentes a um único NULL.
HAS	String	Só são permitidos literais de cadeias constantes no lado direito. Não são permitidas cadeias vazias e NULL .

Para predicados de comparação (<, >, <=, >=, =, !=) e o operando de predicado IN pode ser NULO 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 num valor Bool, Duplo, DateTime ou TimeSpan . Para cada valor analisado com êxito, é criado um predicado com o = operador. Estes predicados e o predicado HAS original são associados a um predicado OR . Por exemplo, uma cadeia de predicado p1 HAS '1.0' é equivalente a p1.String HAS '1.0' OR p1.Double = 1.0, se existirem propriedades p1 com tipos de Cadeia e Duplo .

Verificação de tipos

As expressões de predicado são verificadas por tipo e validadas para garantir que os tipos do lado direito e esquerdo dentro das mesmas correspondem.

Importante

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

Se for especificado um tipo para a propriedade, é aplicada uma verificação de tipo:

Qualquer tipo de propriedade é aceite num literal NULL .

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

Os exemplos das propriedades p1 e p2 do tipo Cadeia e da propriedade p3 do Tipo duplo são apresentados na seguinte tabela:

Cadeia de predicado	É válido?	Notas
`p1.String = 'abc'`	Yes
`p1.String = p2.String`	Yes
`p1.String = NULL`	Yes	`NULL` corresponde a qualquer tipo de lado esquerdo.
`p3.Double = 'abc'`	No	Erro de correspondência do tipo.
`p3.Double = p1.String`	No	Erro de correspondência do tipo.
`p1.String HAS 'abc'`	Yes
`p3.Double HAS '1.0'`	Yes	O literal de cadeia foi analisado com êxito para um valor Duplo .

Se um tipo for omitido para a propriedade, mas for especificado um nome, são executados os seguintes passos:

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

São apresentados exemplos de propriedades p1 e p2 dos tipos Cadeia e Duplo e alguns dos respetivos equivalentes na seguinte tabela:

Cadeia de predicado	Cadeia de predicado com tipo forte equivalente	Notas
`p1 = 'abc'`	`p1.String = 'abc'`
`p1 = true`		Nenhuma propriedade p1 do tipo Bool, pelo que é emitido um erro de propriedade em falta.
`p1 = NULL`	`p1.String = NULL AND p1.Double = NULL`	Para `NULL` o lado direito, presume-se que todas as propriedades correspondentes devem ser `NULL`.
`p1 != NULL`	`p1.String != NULL OR p1.Double != NULL`	Esta é 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`	Este é o equivalente a `p1 = NULL`.
`p1 HAS '1.0'`	`p1.String HAS '1.0' OR p1.Double = 1.0`	O literal da cadeia foi analisado com êxito para um valor Duplo válido.
`p1 HAS 'true'`	`p1.String HAS 'true'`	O literal de cadeia 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`	Esta é uma inversão da expressão anterior.

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

Este cenário é uma generalização da pesquisa em texto completo que utiliza o operando HAS .
Todas as propriedades que correspondem ao tipo do lado direito são tomadas e as expressões resultantes são concatenadas através de uma operação OR .

Os exemplos da propriedade p1 dos tipos Cadeia e Duplo e propriedade p2 dos tipos String e DateTime são apresentados na seguinte tabela:

Cadeia de predicado	Cadeia de predicado com tipo forte equivalente	Notas
`= '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`		Error. Não existe nenhuma propriedade Bool , pelo que é emitido um erro de propriedade em falta.
`= NULL`		Error. 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 existe nenhuma propriedade com o tipo Bool.

Se o operador for omitido juntamente com um nome de propriedade, a HAS operação é assumida.

Funções escalares

As funções escalares devolvem valores escalares.

Funções nativas

As funções escalares suportadas por Azure Time Series Insights Gen1 incluem:

Nome da função	Valor devolvido	Argumentos	Exemplo	Notas
utcNow	DateTime	Nenhuma	utcNow()	Devolve a hora atual no formato UTC. O nome da função é sensível às maiúsculas e minúsculas.

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

Expressões agregadas

As expressões de agregação são utilizadas para criar partições de coleções de eventos e medidas de computação sobre as partições. As expressões de agregação estão divididas nos seguintes tipos:

Expressões de dimensão
Expressões de valores exclusivos
Expressões de histograma de data
Expressões de medida

Expressões de dimensão

Utilize expressões de dimensão dentro de uma cláusula de agregação 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 numa determinada propriedade.	O histograma numérico de temperatura pode resultar num retorno de 10 intervalos de graus.

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

Especifique o tamanho máximo de uma dimensão produzida por uniqueValues e numericHistogram com a cláusula take . Em dateHistogram, o tamanho é calculado ao dividir o intervalo de pesquisa pelo tamanho do intervalo dateHistogram , que especifica através da cláusula breaks .

Por exemplo, uma consulta agregada 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 é 3x60=180. Este resultado significa que uniqueValues pode demorar até 150 000/180 = 833 itens no total.

Expressões de valores exclusivos

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

A avaliação desta expressão JSON resulta num máximo de 100 registos, que são agrupados pela sensorId propriedade Cadeia.

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

Expressões de histograma de data

Utilize uma expressão de histograma de data para agrupar valores de propriedade DateTime em registos de um tamanho especificado.

Uma avaliação desta expressão JSON resulta num conjunto de registos de Carimbo de data/hora arredondados por piso de modo a que cada valor tenha zero segundos.

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

Expressões de histograma numérico

Utilize uma expressão de histograma numérico para agrupar valores de propriedade Duplo num número especificado de registos.

Uma avaliação desta expressão JSON resulta em 10 registos, pelo que o intervalo entre os valores mínimo e máximo da propriedade p1 é dividido em 10 registos.

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

Expressões de medida

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

Utilize uma expressão de contagem para calcular o número de eventos num registo correspondente.

{ "count": {} }

As expressões min, max, avg e sum são utilizadas para calcular o mínimo, o máximo, a média e a soma dos valores de uma propriedade especificada num registo correspondente.

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

Com as expressões de primeira e última medida, 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 é predefinida para a propriedade Carimbo de data/hora $ts. A entrada pode ser de qualquer tipo. A cláusula orderBy suporta apenas os tipos Double e DateTime .

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

Pode utilizar as primeiras e últimas expressões para ajudar a compreender o valor mais antigo ou mais recente de uma propriedade específica. Por exemplo, se tiver uma propriedade chamada deviceID e quiser compreender a mais recente deviceID que enviou um evento, o último é o operador de expressão mais eficiente a utilizar para identificar essas informações.

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

Outro exemplo é utilizar o último para localizar a última localização comunicada de um determinado objeto, como um navio, veículo ou outro objeto em movimento.

Para ilustrar uma consulta que produz a última localização conhecida dos navios numa frota, 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 é utilizar primeiro para encontrar um dispositivo que reporte a menor pressão para cada fábrica:

{
  "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 de dimensão e tipo de medida

Eis as expressões de medida e dimensão suportadas, com base no tipo de propriedade:

Tipo de propriedade	Expressões de dimensão suportadas	Expressões de medida suportadas
Bool	`"uniqueValues"`	`"first"` (entrada), `"last"` (entrada)
DateTime	`"uniqueValues"`, `"dateHistogram"`	`"min"` `"first"` , `"max"`(orderBy, input), `"last”` (orderBy, input)
Duplo	`"uniqueValues"`, `"numericHistogram"`	`"sum"`, `"avg"`, `"min"`, `"max"`, `"first"` (orderBy, input), `"last”` (orderBy, input)
String	`"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 estão divididas nos seguintes tipos:

Cláusulas de span de pesquisa
Cláusulas de predicado
Limitar as cláusulas principais
Limitar cláusulas de aceitação
Limitar cláusulas de exemplo
Cláusulas de quebras
Cláusulas de agregação

Cláusulas de span de pesquisa

Utilize uma cláusula de span de pesquisa para filtrar uma propriedade de Carimbo de Data /Hora incorporada de um evento para um determinado intervalo. O início do intervalo é inclusivo. O fim 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 de span de pesquisa (searchSpan) devem ser expressões válidas do tipo de resultado DateTime . Estas expressões são avaliadas antes da execução da consulta, o que significa que não devem conter quaisquer referências de propriedade.

Cláusulas de predicado

Utilize uma cláusula de predicado para filtrar eventos que satisfaçam o predicado. Deve ser resolvido numa expressão booleana .

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

Filtrar eventos significa executar um predicado representado por uma expressão booleana em cada evento no ambiente. A execução de uma expressão num evento devolve true se o evento tiver de ser incluído em mais operações. false Devolve se o evento tiver de ser omitido de processamento adicional.

Nota

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

Limitar as cláusulas principais

Utilize uma cláusula top *limit para obter um número especificado de valores por ordem ascendente ou descendente. O número de valores é limitado de acordo com a contagem especificada.

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

Limitar cláusulas de aceitação

Pode utilizar uma cláusula de aceitação de limite como uma forma rápida de obter um conjunto de valores sem ordem específica. O número de valores devolvidos é limitado pela entrada especificada.

{ "take": 10 }

Limitar cláusulas de exemplo

Utilize uma cláusula *limitar exemplo para obter uma amostra estatisticamente representativa de um conjunto de valores. O número de valores devolvidos é limitado pela entrada especificada.

{ "sample": 10 }

Cláusulas de quebras

Utilize uma cláusula *breaks nas expressões de histograma para especificar a forma como um intervalo deve ser dividido.

Para histogramas de data, deve especificar o tamanho dos limites de intervalo e intervalo de datetime. Pode fazê-lo, a menos que o histograma se baseie numa propriedade de Carimbo de Data/Hora incorporada em que os limites são determinados com base no intervalo de pesquisa:

Os limites de intervalo são opcionais e podem ser utilizados. Por exemplo, pode utilizá-los quando forem determinados com base num intervalo de pesquisa se os limites do intervalo forem omitidos.
Para histogramas numéricos, deve especificar o número de quebras. Pode determinar os limites de intervalo com base nos valores mínimos e máximos 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 de agregação

Utilize uma cláusula de agregação para particionar um conjunto de eventos por uma determinada propriedade enquanto mede os valores de outras propriedades do evento.

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

O exemplo JSON seguinte 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"
            }
          }
        }
      ]
    }
  ]
}

Nota

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

O exemplo JSON seguinte 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"
            }
          }
        }
      ]
    }
  ]
}

Nota

Atualmente, não é suportado ter mais do que um elemento numa matriz agregada.
No entanto, uma definição de agregação pode incluir uma matriz aninhada que especifica um lattice multidimensional mais flexível.

O exemplo JSON seguinte 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"
              }
            }
          }
        ]
      }
    }
  ]
}

Ver também

Para obter mais informações sobre as APIs Azure Time Series Insights Gen1, veja APIs gen1.
Para saber mais sobre os parâmetros de pedido e autenticação, veja Autenticação e autorização.
Saiba mais sobre Azure Time Series Insights Gen1 ao rever a documentação do Gen1.

Partilhar via

sintaxe de consulta Azure Time Series Insights Gen1

Resumo

Modelo de dados

Propriedades do evento

Tipos de evento

Expressões escalares

Expressões constantes

Tipos primitivos anuláveis

Expressões de referência de propriedade

Expressões de comparação

Expressões aritméticas

Predicar expressões de cadeia

Literais suportados

Tipos de operando suportados

Verificação de tipos

Funções escalares

Funções nativas

Expressões agregadas

Expressões de dimensão

Expressões de valores exclusivos

Expressões de histograma de data

Expressões de histograma numérico

Expressões de medida

Suporte de dimensão e tipo de medida

Cláusulas

Cláusulas de span de pesquisa

Cláusulas de predicado

Limitar as cláusulas principais

Limitar cláusulas de aceitação

Limitar cláusulas de exemplo

Cláusulas de quebras

Cláusulas de agregação

Ver também

Recursos adicionais