sintaxis de consulta de Azure Time Series Insights Gen1

Precaución

Este es un artículo de Gen1.

En este artículo se describe el formato de solicitud de consulta y la sintaxis de la API de consulta de Azure Time Series Insights Gen1.

Resumen

Importante

• Las solicitudes de consulta deben estar en formato JSON.
• Las cargas de solicitud HTTP realizadas en la API de consulta deben cumplir el formato especificado en este artículo.

El idioma se subdivide en los siguientes elementos:

• Expresiones escalares, que producen valores escalares. Las expresiones escalares incluyen expresiones de cadena de predicado, expresiones de comparación y expresiones aritméticas.
• Funciones escalares, que devuelven valores escalares.
• Expresiones de agregado, que se usan para particionar colecciones de eventos y medidas de proceso sobre las particiones.
• Cláusulas, que forman los componentes constituyentes de las consultas JSON o una parte de una expresión.

Modelo de datos

La API de consulta de Azure Time Series Insights Gen1 funciona en los datos almacenados como eventos individuales dentro de un entorno. Cada evento es un conjunto de pares de nombre de propiedad y valor .

Propiedades de evento

Las propiedades de evento pueden ser de uno de los siguientes tipos primitivos: Bool, DateTime, Double o String. Todos los tipos primitivos admiten valores NULL.

Nota

Los formatos de origen de eventos personalizados pueden admitir un conjunto mayor de tipos de valor. Azure Time Series Insights Gen1 deduce el tipo primitivo más cercano y, a continuación, convierte los tipos personalizados en ellos en la entrada.

Todos los eventos tienen las siguientes propiedades integradas con un nombre y un tipo predefinidos:

Nombre de propiedad	Tipo de propiedad	Definición
$ts	DateTime	Marca de tiempo del evento
$esn	String	Nombre de origen de eventos

• Marca de tiempo del evento

  De forma predeterminada, el origen del evento proporciona un valor de marca de tiempo de evento. Por ejemplo, los eventos procedentes de un centro de IoT tendrían su tiempo en cola como una marca de tiempo.

  Los clientes pueden modificar este comportamiento configurando otra propiedad de evento en su lugar. Las propiedades de marca de tiempo personalizadas se pueden especificar en event hubs e IoT Hubs.

• Nombre de origen de eventos

  El nombre del origen del evento es el nombre que se muestra para el origen del evento desde el que Azure Time Series Insights Gen1 ha recibido el evento. Los nombres de origen de eventos están asociados a un evento determinado en el momento de la entrada.

  Importante

  • Los nombres de origen del evento permanecen sin cambios durante la vigencia del evento.
  • Si se modifica el nombre de un origen de eventos, los eventos existentes llevan el nombre de origen del evento anterior. Los nuevos eventos llevarán el nuevo nombre de origen del evento.

Tipos de eventos

Las propiedades de evento personalizadas se identifican de forma única y se hace referencia a las expresiones de consulta por nombre y tipo. Un evento puede tener más de una propiedad con el mismo nombre y tipos diferentes. Las propiedades con el mismo nombre, pero distintos tipos pueden dar lugar a la división de tipos de entrada.

Un valor de propiedad de evento de tipo String se puede almacenar como una propiedad con un tipo diferente en los casos siguientes:

• Si un valor string es un valor Double válido, se almacena tanto como Double como String.
• Si un valor string es un valor DateTime válido, se almacena solo como DateTime .

Query API convierte literales de cadenas vacíos ("") null en en la salida.

Azure Time Series Insights Gen1 tiene compatibilidad limitada con los siguientes valores dentro del tipo Double: Double.NaN, Double.PositiveInfinityy Double.NegativeInfinity. Estos valores se convierten null en durante la entrada, pero si la evaluación de consultas genera uno de estos valores, el valor se evalúa y serializa como una cadena en respuesta.

Puede pasar estos valores como Cadenas para la entrada, por lo que en las expresiones de consulta, estos valores también deben pasarse como Cadenas.

Los esquemas de eventos describen las propiedades de un evento. Un esquema de eventos contiene el nombre de un origen de eventos y el conjunto ordenado de propiedades para el evento. Los distintos eventos pueden tener esquemas diferentes o compartir el mismo esquema.

Expresiones escalares

Las expresiones escalares generan valores escalares. Las expresiones escalares se dividen en los siguientes tipos:

• Expresiones constantes
• Expresiones de referencia de propiedades
• Expresiones de comparación
• Expresiones aritméticas
• Expresiones de cadena de predicado

Expresiones constantes

Se representan expresiones constantes mediante los siguientes literales para cada uno de los tipos primitivos:

Tipo primitivo	Representación JSON	Ejemplo JSON	Notas
Bool	Como tipo booleano JSON	true, false
DateTime	Como objeto anidado con una propiedad dateTime única en formato yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFKISO 8601.	{"dateTime":"2016-08-01T00:00:00.000Z"}
Double	Número JSON convertido en el intervalo Double.	1.23e45, 123	Los desbordamientos dobles generarán un error.
String	Tipo de cadena JSON	"abc"
TimeSpan	Como objeto anidado con una propiedad timeSpan única en formato ISO 8601 : P[n]Y[n]M[n]DT[n]H[n]M[n]S.	{"timeSpan":"P1Y2M3DT4M5.67S"}

Tipos primitivos que aceptan valores NULL

Los tipos de datos primitivos admiten valores NULL. null Los valores de los tipos primitivos se expresan en JSON de la siguiente manera:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Expresiones de referencia de propiedades

Se usa una expresión de referencia de propiedad para tener acceso a los valores de propiedades no integradas de un evento. Las propiedades no integradas incluyen cualquier propiedad personalizada más allá de las predeterminadas que se incluyen automáticamente en un esquema de eventos.

El tipo de resultado de una expresión de referencia de propiedad es el tipo primitivo de la propiedad. Las propiedades del esquema de eventos se identifican de forma única por nombre y tipo, y la expresión de referencia requiere que se especifiquen ambos.

• Ejemplos de JSON:

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

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

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

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

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

Se usa una expresión de referencia de propiedad integrada para tener acceso a las propiedades integradas de un evento. Las propiedades integradas son solo las propiedades que se definen automáticamente en un esquema de eventos.

El tipo de resultado de una expresión de referencia de propiedad integrada es el tipo primitivo de la propiedad. Solo se hace referencia a las propiedades integradas por nombre; por lo tanto, no se necesita ningún tipo en la expresión de referencia:

{ "builtInProperty": "$esn" }

Expresiones de comparación

Se admiten las siguientes expresiones de comparación booleanas :

Nombre de propiedad en JSON	Descripción
eq	Igual
in	En (igual que cualquiera)
phrase	Contiene una frase
startsWith	Empieza por
endsWith	Termina con la frase
regex	Coincide con la expresión regular
lt	Menor que
lte	Menor o igual que
gt	Mayor que
Gte	Mayor o igual que

Importante

• Todas las expresiones de comparación toman los tipos primitivos de argumentos de izquierda y derecha y devuelven un valor booleano que representa el resultado de la comparación.
• Ambos tipos de argumentos de izquierda y derecha en las comparaciones deben coincidir.
• Todos los tipos se convierten implícitamente solo a sí mismos y no se admiten conversiones explícitas.

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

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

En la tabla siguiente se muestran los tipos de argumentos admitidos para cada una de las expresiones de comparación:

Tipo de argumento	Operación de comparación admitida
Bool	eq, in
DateTime	eq, in, lt, lte, gt, gte
Double	eq, in, lt, lte, gt, gte
String	eq, in, phrase, startsWith, endsWith, regex
TimeSpan	eq, in, lt, lte, gt, gte

El literal NULL solo se puede usar con los siguientes operadores de comparación: eq o in.

• El operador eq da como resultado true si ambos lados son null valores. De lo contrario, el operador da como falseresultado .
• Para otras operaciones, el error se genera para el literal NULL y el comportamiento no está definido para las propiedades de valor NULL (cualquier operación de comparación que tenga como falseresultado ).
• Un null valor precede a los valores no NULL en los ordenaciones de ordenación (por ejemplo, si se aplica la ordenación por una propiedad para devolver una lista de eventos).

Azure Time Series Insights Gen1 admite las siguientes expresiones lógicas booleanas:

Nombre de propiedad en JSON	Descripción
and	Toma un conjunto no vacío de argumentos booleanos y devuelve true si todos se evalúan como true.
or	Toma un conjunto no vacío de argumentos booleanos y devuelve true si alguno de ellos se evalúa como true.
not	Toma un único argumento booleano y devuelve su valor negado.

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

La propiedad stringComparison es opcional. De forma predeterminada, su valor es OrdinalIgnoreCase, lo que hace que el uso de mayúsculas y minúsculas de oraciones se omita en comparaciones.

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

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

Expresiones aritméticas

Azure Time Series Insights Gen1 admite las siguientes expresiones aritméticas:

Nombre de propiedad en JSON	Descripción
add	Suma
sub	Resta
Mult	Multiplicación
div	División

Todas las expresiones aritméticas toman los argumentos izquierdo y derecho de los tipos primitivos y devuelven un valor que representa el resultado de la operación.

Todos los tipos se convierten implícitamente solo a sí mismos y no se admiten conversiones explícitas.

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

En la tabla siguiente se muestran los tipos de argumentos admitidos para cada una de las expresiones aritméticas:

Operación	Tipo izquierdo	Tipo derecho	Tipo de resultado
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

Expresiones de cadena de predicado

Las expresiones de cadena de predicado booleano contienen predicados booleanos que se representan como expresiones legibles humanas denominadas cadenas de predicado.

Ejemplos de cadenas de predicado:

Cadena de predicados	Descripción
Description HAS 'hello world'	true para eventos que contienen la frase hello world de la propiedad Description en todos los orígenes de eventos
'hello world'	true para eventos que contienen la frase hello world
startsWith(Status, 'go')	true para eventos con Estado a partir de go
endsWith(Status, 'oD')	true para eventos con Estado que termina con od
startsWith_cs(Status, 'Go')	true para eventos con Estado a partir de Go
endsWith_cs(Status, 'od')	true para eventos con Estado a partir de od
matchesRegex(s, '^G*')	true para eventos con Status que coincida con la expresión regular ^G*
PointValue.Double = 3.14	true para eventos con pointValue doble igual a 3.14
Status IN ('Good','Bad')	true para eventos con Estado que contiene Good o Bad
PointValue > 3.14 AND Status.String = 'Good'	true para eventos con PointValue mayor que 3.14 y estado de cadena de Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'	true para eventos con PointValue mayor que 3.14 y Status de Good o Bad y Description que no contienen la frase hello world

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

La expresión de la cadena de predicado se evalúa en una expresión booleana JSON. Debe cumplir la siguiente gramática (simplificada):

Expresión booleana JSON	Formulario 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 datos primitivos gen1 se admiten en expresiones de cadena de predicado.

A diferencia de las expresiones de referencia de propiedades JSON, se puede omitir un tipo para una propiedad, en cuyo caso se deduce automáticamente un tipo.

Literales admitidos

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

Tipos de operando admitidos

Operación	Tipos admitidos	Notas
<, >, <, >	Double, DateTime, TimeSpan
=, =, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> es equivalente para !=
+, -, *, /	Double, DateTime, TimeSpan
IN	String, Bool, Double, DateTime, TimeSpan, NULL	Todos los operandos deben ser del mismo tipo o deben ser una constante NULL. Varios VALORES NULLson equivalentes a un único VALOR NULL.
HAS	String	Solo los literales de cadenas constantes se permiten en el lado derecho. No se permiten cadenas vacías y NULL .

Para los predicados de comparación (<, , ><=, >=, =, !=) y el operando de predicado IN pueden ser NULL o tener un solo tipo.

Para las expresiones con un predicado HAS , el literal constante del lado derecho del operando HAS se puede expandir en varios tipos. Además, el literal constante del lado derecho del operando HAS se analiza en un valor Bool, Double, DateTime o TimeSpan . Para cada valor analizado correctamente, se crea un predicado con el = operador . Estos predicados y el predicado HAS original se unen a un predicado OR . Por ejemplo, una cadena p1 HAS '1.0' de predicado es equivalente a p1.String HAS '1.0' OR p1.Double = 1.0, si existen propiedades p1 con tipos String y Double .

Comprobación de tipos

Las expresiones de predicado están marcadas por tipos y validadas para asegurarse de que los tipos de mano derecha y izquierda dentro de ellos coincidan.

Importante

• Cuando las constantes a la izquierda y a la derecha de un operando no coinciden, se produce un error.
• También se produce un error si no se permite una operación en o entre tipos específicos.

• Si se especifica un tipo para la propiedad , se aplica una comprobación de tipo:

  • Cualquier tipo de propiedad se acepta en un literal NULL .

  • De lo contrario, los tipos de lado izquierdo y derecho deben coincidir.

    En la tabla siguiente se muestran ejemplos de propiedades p1 y p2 del tipo String y la propiedad p3 del tipo Double :

    Cadena de predicados	¿Es válido?	Notas
    p1.String = 'abc'	Sí
    p1.String = p2.String	Sí
    p1.String = NULL	Sí	NULL coincide con cualquier tipo de lado izquierdo.
    p3.Double = 'abc'	No	No coinciden los tipos.
    p3.Double = p1.String	No	No coinciden los tipos.
    p1.String HAS 'abc'	Sí
    p3.Double HAS '1.0'	Sí	El literal de cadena se ha analizado correctamente en un valor Double .

• Si se omite un tipo para la propiedad pero se especifica un nombre, se realizan los pasos siguientes:

  1. Se toman todas las propiedades con un nombre y tipos especificados.
  2. Los operandos de lado izquierdo y derecho se agrupan en pares por tipo.
  3. Los pares se concatenan mediante operaciones AND .

  • En la tabla siguiente se muestran ejemplos de propiedades p1 y p2 de los tipos String y Double y algunos de sus equivalentes:

    Cadena de predicados	Cadena de predicado con tipo seguro equivalente	Notas
    p1 = 'abc'	p1.String = 'abc'
    p1 = true		No hay ninguna propiedad p1 de tipo Bool, por lo que se emite un error de propiedad que falta.
    p1 = NULL	p1.String = NULL AND p1.Double = NULL	En NULL el caso de la derecha, se supone que todas las propiedades coincidentes deben ser NULL.
    p1 != NULL	p1.String != NULL OR p1.Double != NULL	Se trata de una inversión de la expresión 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 es el equivalente de p1 = NULL.
    p1 HAS '1.0'	p1.String HAS '1.0' OR p1.Double = 1.0	El literal de cadena se ha analizado correctamente en un valor Double válido.
    p1 HAS 'true'	p1.String HAS 'true'	El literal de cadena se ha analizado correctamente en Bool, pero no p1. La propiedad Bool existe.
    p1 = p2	p1.String = p2.String AND p1.Double = p2.Double
    p1 != p2	p1.String != p2.String OR p1.Double != p2.Double	Se trata de una inversión de la expresión anterior.

• Tanto el nombre de la propiedad como el tipo se pueden omitir para una propiedad del lado izquierdo si el tipo de propiedad del lado derecho está bien definido. Esto es así siempre que el lado derecho tiene literales constantes y no solo contiene un NULL literal.

  • Este escenario es una generalización de la búsqueda de texto completo que usa el operando HAS .

  • Se toman todas las propiedades que coinciden con el tipo de lado derecho y las expresiones resultantes se concatenan a través de una operación OR .

  • En la tabla siguiente se muestran ejemplos de propiedad p1 de los tipos String y Double y property p2 de los tipos String y DateTime :

    Cadena de predicados	Cadena de predicado con tipo seguro equivalente	Notas
    = 'abc'	p1.String = 'abc' OR p2.String = 'abc'
    != 'abc'	p1.String != 'abc' AND p2.String != 'abc'	Inversión de la expresión anterior
    = 1.0	p1.Double = 1.0
    = dt'2000-01-02T03:04:05'	p2.DateTime = dt'2000-01-02T03:04:05'
    = true		Error. No existe ninguna propiedad Bool , por lo que se genera un error de propiedad que falta.
    = NULL		Error. No se permite omitir el nombre de propiedad del NULL lado derecho.
    IN (NULL)		Igual que el error 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'	No hay ninguna propiedad con el tipo Bool.

• Si el operador se omite junto con un nombre de propiedad, se asume la HAS operación.

Funciones escalares

Las funciones escalares devuelven valores escalares.

Funciones nativas

Entre las funciones escalares admitidas por Azure Time Series Insights Gen1 se incluyen las siguientes:

Nombre de función	Valor devuelto	Argumentos	Ejemplo	Notas
utcNow	DateTime	Ninguno	utcNow()	Devuelve la hora actual en formato UTC. El nombre de la función distingue mayúsculas de minúsculas.

La función UTC ahora devuelve un valor DateTime , que contiene la hora actual en formato UTC. No acepta ningún argumento.

Expresiones de agregado

Las expresiones de agregado se usan para particionar colecciones de eventos y medidas de proceso sobre las particiones. Las expresiones de agregado se dividen en los siguientes tipos:

• Expresiones de dimensión
• Expresiones de valores únicos
• Expresiones de histograma de fecha
• Expresiones de medida

Expresiones de dimensión

Las expresiones de dimensión se usan dentro de una cláusula aggregates para particionar un conjunto de eventos y asignar una clave escalar a cada partición.

Tipos de expresión de dimensión:

Nombre de propiedad en JSON	Descripción	Ejemplo
uniqueValues	Los valores de dimensión del resultado son valores exactos de una propiedad determinada.
dateHistogram	Los valores de dimensión del resultado son intervalos de tiempo de una propiedad determinada.	El histograma de fecha de la marca de tiempo podría dar lugar a intervalos de 10 horas para un intervalo de búsqueda de 10 horas.
numericHistogram	Los valores de dimensión del resultado son intervalos de valores en una propiedad determinada.	El histograma numérico de temperatura podría dar lugar a un retorno de 10 intervalos de grados.

Azure Time Series Insights Gen1 restringe la cardinalidad máxima o el tamaño máximo de lattice de una consulta de agregado de entrada a 150 000 celdas. Para calcular la cardinalidad de una consulta de agregado, se multiplican los tamaños de todas las dimensiones de la consulta. Siempre que el producto sea inferior a 150 000, la consulta se acepta para su ejecución. Si el producto es igual o menor que 150 000, se rechaza la consulta.

Especifique el tamaño máximo de una dimensión generada por uniqueValues y numericHistogram mediante la cláusula take . En dateHistogram, el tamaño se calcula dividiendo el intervalo de búsqueda por el tamaño del intervalo dateHistogram , que se especifica mediante la cláusula breaks .

Por ejemplo, una consulta de agregado tiene el intervalo de búsqueda establecido de "2017-11-15T16:00:00.000Z" a "2017-11-15T19:00:00.000Z" = 3 horas. Si la consulta incluye dateHistogram con la cláusula breaks , se establece en 1 minuto (dimensión 1) y uniqueValues sobre la propiedad XYZ, el tamaño de dimensión dateHistogram es 3x60=180. Este resultado significa que uniqueValues puede tardar hasta 150 000/180 = 833 elementos totales.

Expresiones de valores únicos

Se usa una expresión de valores únicos para agrupar un conjunto de eventos por los valores de una propiedad de evento especificada.

La evaluación de esta expresión JSON da como resultado hasta 100 registros, que se agrupan mediante la sensorId propiedad String.

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

Expresiones de histograma de fecha

Se usa una expresión de histograma de fecha para agrupar los valores de propiedad DateTime en cubos de un tamaño especificado.

Una evaluación de esta expresión JSON da como resultado un conjunto de registros timestamp redondeados de forma que cada valor tiene ceros en segundos.

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

Expresiones de histograma numérico

Se usa una expresión de histograma numérico para agrupar valores de propiedad Double en un número especificado de cubos.

Una evaluación de esta expresión JSON da como resultado 10 registros, por lo que el intervalo entre los valores mínimo y máximo de la propiedad p1 se divide en 10 cubos.

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

Expresiones de medida

Las expresiones de medida se usan dentro de las cláusulas de agregado para calcular un valor escalar en un conjunto de eventos. Por ejemplo, una expresión de medida es el cálculo del valor máximo medido por un sensor de temperatura durante las últimas 24 horas.

Se usa una expresión count para calcular el número de eventos dentro de un cubo correspondiente.

{ "count": {} }

Use expresiones min, max, avg y sum para calcular el mínimo, máximo, promedio de y la suma de los valores de una propiedad especificada dentro de un cubo correspondiente.

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

Con las expresiones de primera y última medida, puede obtener el valor de una propiedad especificada A que corresponde al valor mínimo o máximo de la propiedad B.

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

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

La cláusula orderBy es opcional y tiene como valor predeterminado la propiedad Timestamp$ts. La entrada puede ser de cualquier tipo. La cláusula orderBy solo admite tipos Double y DateTime .

Si la propiedad B es un tipo DateTime , obtendrá el valor más reciente o el más antiguo de la propiedad A.

Puede usar las expresiones primero y última para ayudar a comprender el valor más antiguo o más reciente de una propiedad específica. Por ejemplo, si tiene una propiedad denominada deviceID y quiere comprender lo más reciente deviceID que envió un evento, por último es el operador de expresión más eficaz que se usará para identificar esa información.

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

Otro ejemplo es usar last para buscar la última ubicación notificada de un objeto determinado, como un barco, un vehículo u otro objeto móvil.

Para ilustrar una consulta que genera la última ubicación conocida de los buques de una flota, puede crear una consulta similar a la siguiente:

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

Otro ejemplo es usar primero para buscar un dispositivo que informe de la presión más baja 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"
            }
          }
        }
      ]
    }
  ]
}

Compatibilidad con tipos de medida y dimensión

Estas son las expresiones de medida y dimensión admitidas, basadas en el tipo de propiedad:

Tipo de propiedad	Expresiones de dimensión admitidas	Expresiones de medida admitidas
Bool	"uniqueValues"	"first" (entrada), "last" (entrada)
DateTime	"uniqueValues", "dateHistogram"	"min", , "max""first" (orderBy, input), "last” (orderBy, input)
Double	"uniqueValues", "numericHistogram"	"sum", "avg", "min", , "first""max"(orderBy, input), "last” (orderBy, input)
String	"uniqueValues"	"first" (entrada), "last" (entrada)

Cláusulas

Las cláusulas forman componentes constituyentes de consultas JSON o parte de una expresión. Las cláusulas se dividen en los siguientes tipos:

• Cláusulas de intervalo de búsqueda
• Cláusulas de predicado
• Limitar cláusulas superiores
• Limitar cláusulas take
• Limitar cláusulas de ejemplo
• Cláusulas de saltos
• Cláusulas de agregados

Cláusulas de intervalo de búsqueda

Se usa una cláusula de intervalo de búsqueda para filtrar una propiedad Timestamp integrada de un evento a un intervalo determinado. El inicio del intervalo es inclusivo. El final del intervalo es exclusivo.

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

Las propiedades from y to en la cláusula search span (searchSpan) deben ser expresiones válidas del tipo de resultado DateTime . Estas expresiones se evalúan antes de la ejecución de la consulta, lo que significa que no deben contener ninguna referencia de propiedad.

Cláusulas de predicado

Se usa una cláusula de predicado para filtrar eventos que satisfacen el predicado. Debe resolverse en una expresión booleana .

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

Para filtrar eventos significa ejecutar un predicado representado por una expresión booleana en cada evento del entorno. La ejecución de una expresión en un evento devuelve true si el evento debe incluirse en otras operaciones. false Devuelve si se debe omitir el evento del procesamiento posterior.

Nota:

Los eventos siempre se filtran por intervalo de búsqueda, además de cualquier filtrado especificado dentro de una expresión de predicado.

Limitar cláusulas superiores

Se usa una cláusula superior *limit para obtener un número especificado de valores en orden ascendente o descendente. El número de valores está limitado según el recuento especificado.

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

Limitar cláusulas take

Puede usar una cláusula limit take como una manera rápida de obtener un conjunto de valores en ningún orden determinado. El número de valores devueltos está limitado por la entrada especificada.

{ "take": 10 }

Limitar cláusulas de ejemplo

Use una cláusula de ejemplo *limit para obtener una muestra estadísticamente representativa de un conjunto de valores. El número de valores devueltos está limitado por la entrada especificada.

{ "sample": 10 }

Cláusulas de saltos

Se usa una cláusula *breaks en expresiones de histograma para especificar cómo se debe dividir un intervalo.

En el caso de los histogramas de fecha, debe especificar el tamaño del intervalo de fecha y los límites del intervalo. Para ello, a menos que el histograma se base en una propiedad de marca de tiempo integrada en la que se determinan los límites en función del intervalo de búsqueda:

• Los límites de intervalo son opcionales y se pueden usar. Por ejemplo, puede usarlos cuando se determinan en función de un intervalo de búsqueda si se omiten los límites del intervalo.
• Para histogramas numéricos, debe especificar el número de saltos. Los límites de intervalo se determinan en función de los valores mínimo y máximo de una propiedad.

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

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

Cláusulas de agregados

Se usa una cláusula aggregates para particionar un conjunto de eventos por una propiedad determinada mientras se miden los valores de otras propiedades de evento.

Las medidas se evalúan en cada partición generada por la expresión de dimensión.

• En el ejemplo JSON siguiente se calculan las temperaturas medias, mínimas y máximas por identificador de 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

  Una cláusula aggregates es una matriz que permite especificar más de una agregación en el nivel superior.

• En el ejemplo JSON siguiente se calcula la temperatura media por ciudad y por fabricante de forma independiente:

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

  • Actualmente no se admite tener más de un elemento en una matriz de agregados.
  • Sin embargo, una definición de agregación puede incluir una matriz anidada que especifica una red multidimensional más flexible.

• En el ejemplo JSON siguiente se calcula la temperatura media por identificador de 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"
                }
              }
            }
          ]
        }
      }
    ]
  }
  

Consulte también

• Para obtener más información sobre las API de Azure Time Series Insights Gen1, consulte API de Gen1.

• Para obtener información sobre los parámetros de solicitud y autenticación, consulte Autenticación y autorización.

• Para más información sobre Azure Time Series Insights Gen1, revise la documentación de Gen1.