Sintaxis de expresión de serie temporal de Azure Time Series Insights Gen2

Información general

Expresión de serie temporal (TSX) es un lenguaje de expresiones basado en cadenas con escritura segura. TSX se usa para representar las siguientes entidades en una consulta de serie temporal.

  • Filter
  • Value
  • Agregación

Expresiones de filtro

Las expresiones de filtro se usan para representar cláusulas booleanas. En la tabla siguiente se enumeran ejemplos de filtros:

TSX Descripción
$event.PointValue.Double = 3.14 true para eventos con double PointValue igual a 3.14
$event.PointValue > 3.14 AND $event.Status.String = 'Good' true para eventos con PointValue mayor que 3.14 y estado de cadena Good
$event.$ts > dt'2018-11-01T02:03:45Z' true para eventos con una marca de tiempo mayor que 2018-11-01T02:03:45Z
$event.PointEval.Bool = true true para eventos con PointValue igual a true

Expresiones de valor

Las expresiones de valor se usan para representar el valor de las variables numéricas y categóricas. Una expresión de valor puede ser una expresión de referencia de propiedad de tipo Double o Long.

Por ejemplo:

TSX Notas
$event.Temperature.Double El último token de cualquier expresión de valor (en este caso Double) se lee como tipo de la propiedad .
$event.Temperature Se supone que el tipo es Double para una propiedad a la que accede un único token.
$event['Temperature-Celsius'] Use [ y ] para los tokens de escape que tengan caracteres especiales. Además, use \ entre corchetes para escapar los siguientes caracteres: \ y '.
$event.Temperature.Celsius.Double Use . para acceder a las propiedades anidadas. Al acceder a las propiedades anidadas, se requiere el tipo.
$event.Temperature['Celsius-C'].Double Use [ y ] para los tokens de escape que tengan caracteres especiales al acceder a propiedades anidadas. Además, use \ entre corchetes para escapar los siguientes caracteres: \ y '. Al acceder a las propiedades anidadas, se requiere el tipo.
$event['Temperature']['Celsius'].Double El uso de [ y ] para los tokens de escape se permite en cualquier token.

Tipo de variable numérica

El resultado de la expresión de valor debe ser de tipo Double o Long .

Tipo de variable de agregado

El resultado de la expresión de valor puede ser de cualquier tipo admitido.

Tipo de variable categórica

El resultado de la expresión de valor solo puede ser de tipo String o Long .

Expresiones de agregación

Las expresiones de agregado se usan para representar la operación de agregación que se usará en la consulta. Una expresión de agregado da como resultado un valor único para cada intervalo. Las expresiones de agregado se pueden aplicar en variables numéricas y de agregado.

Expresiones de agregación: tipo de variable numérica

Las variables numéricas deben hacer referencia a $value.

Estas son las funciones de agregado admitidas.

Función de agregado Ejemplo Descripción
min min($value) Calcula el mínimo de por $value intervalo. Evita valores null . No se puede usar con interpolación.
max max($value) Calcula el máximo de por $value intervalo. Evita valores null . No se puede usar con interpolación.
sum sum($value) Calcula la suma de $value todos los eventos del intervalo. Evita valores null . No se puede usar con interpolación.
avg avg($value) Calcula el promedio de $value todos los eventos del intervalo. Evita valores null . No se puede usar con interpolación.
first first($value) Devuelve $value el primer evento que se produce en el intervalo por marca de tiempo de evento. No evitanull valores. No se puede usar con interpolación.
last last($value) Devuelve $value el último evento que se produjo en el intervalo por marca de tiempo de evento. No evitanull valores. No se puede usar con interpolación.
median median($value) Devuelve $value el evento intermedio en el intervalo por marca de tiempo del evento. No evitanull valores. No se puede usar con interpolación.
stdev stdev($value) Devuelve $value la desviación estándar de los eventos en el intervalo. Evita valores null . No se puede usar con interpolación.
twsum twsum($value) Devuelve $value la suma ponderada de tiempo de los eventos en el intervalo. Requiere interpolación.
twavg twavg($value) Devuelve $value el promedio ponderado de tiempo de los eventos en el intervalo. Requiere interpolación.
left left($value) Devuelve en $value el borde izquierdo del intervalo especificado. Requiere interpolación.
right right($value) Devuelve en $value el borde derecho del intervalo especificado. Requiere interpolación.

Expresiones de agregación: tipo de variable de agregado

Las variables de agregado deben hacer referencia a una propiedad en la carga del evento.

Estas son las funciones de agregado admitidas.

Aggregate, función Ejemplo Descripción
count count() Devuelve el número de eventos por intervalo.
min min($event.Temperature.Double) Calcula el mínimo de la propiedad Temperature por intervalo. Evita valores null .
max max($event.Temperature.Long) Calcula el máximo de la propiedad Temperature por intervalo. Evita valores null .
sum sum($event.Temperature.Double) Calcula la suma de la propiedad Temperature en todos los eventos del intervalo. Evita valores null .
avg avg($event.Temperature.Long) Calcula el promedio de la propiedad Temperature en todos los eventos del intervalo. Evita valores null .
first first($event.Temperature.String) Devuelve el primer valor (por marca de tiempo de evento) de la propiedad Temperature de todos los eventos del intervalo. No evitanull valores.
last last($event.Temperature.String) Devuelve el último valor (por marca de tiempo de evento) de la propiedad Temperature de todos los eventos del intervalo. No evitanull valores.
median median($event.Temperature.String) Devuelve el valor intermedio (por marca de tiempo de evento) de la propiedad Temperature de todos los eventos del intervalo. No evitanull valores.
stdev stdev($event.Temperature.String) Calcula la desviación estándar de la propiedad Temperature por intervalo. Evita valores null .

Para un tipo de variable de agregado , estas funciones se pueden combinar en la expresión de agregado. Por ejemplo: max($event.Temperature.Long) - min($event.Temperature.Long).

Sintaxis

En esta sección se describen los conceptos básicos de sintaxis y los operadores de consulta que se concatenan para formar expresiones.

Literales admitidos

Nota

Los literales siguientes se usan para formar expresiones, consulte el artículo Tipos de datos admitidos para obtener la lista completa de tipos de datos.

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

Tipos de operando admitidos

Operación Tipos admitidos Notas
<, >, <, > Double, Long, DateTime, TimeSpan
=, =, <> Double, Long, String, Bool, DateTime, TimeSpan, NULL <> es equivalente a !=
+, -, *, / Double, Long, DateTime, TimeSpan

Para las expresiones de comparación (<, , ><=, >=, =, !=), los operandos pueden ser NULL o ser del mismo tipo. En cada expresión de predicado, se validan los tipos de operandos de lado izquierdo (LHS) y del lado derecho (RHS) para que coincidan. Los errores se producen cuando los tipos de LHS y RHS no están de acuerdo o no se permite una operación en tipos concretos.

Nota

El tipo de cadena no acepta valores NULL en el almacenamiento intermedio:

  • La comparación de String con NULL y la cadena vacía ("") se comporta de la misma manera: $event.p1.String = NULL es equivalente a $event.p1.String = ''.
  • La API puede devolver valores NULL incluso si los eventos originales contenían cadenas vacías.

En el futuro, el mismo comportamiento estará en almacenamiento en frío.

No dependa de los valores NULL de las columnas String y las trate de la misma manera que las cadenas vacías.

  • Se aplica una comprobación de tipos:
    • Cualquier tipo de propiedad se acepta en un NULL literal.
    • Los tipos de LHS y RHS deben coincidir.

Estos son ejemplos de propiedades p1 y p2 de tipo String, propiedad p3 de tipo Double y una propiedad anidada almacenada como p4.p5 de tipo Double:

Filtrar ¿Es válido? Notas
$event.p1.String = 'abc'
$event.p1.String = $event.p2.String
$event.p1.String = NULL NULL coincide con cualquier tipo de lado izquierdo.
$event.p3.Double = 'abc' No No coinciden los tipos.
$event.p3.Double = $event.p1.String No No coinciden los tipos.
$event.p1 = 'abc' No No coinciden los tipos.
$event.p1 = 1 No No coinciden los tipos.
$event.p1 = true No No coinciden los tipos.
$event.p1 = NULL p1 es el único token usado. Interpretado como $event.p1.Double = NULL
$event['p1'] != NULL ['p1'] es el único token usado. Interpretado como $event['p1'].Double != NULL
$event.p4.p5 = 0.0 No Sintaxis de referencia de propiedad no válida. Se debe especificar un tipo en LHS de comparación.
$event.p4.p5.Double = 0.0

Funciones escalares admitidas

A continuación se muestra la lista de funciones escalares por categorías:

Funciones de conversión

Nombre de función Firma Ejemplo Notas
toDouble Double toDouble (value: String, Double, Long) toDouble($event.value.Long) Convierte los argumentos en Double.
toLong Long toLong (value: String, Double, Long) toLong($event.value.Double + 1.0) Convierte los argumentos en Long.
toString String toString (value: String, Double, Long) toString($event.value.Double) Convierte argumentos en String.

Funciones matemáticas

Nombre de función Firma Ejemplo Notas
round Double round(value:Double) round($event.value.Double) Redondea un número flotante de doble precisión a la integral más cercana.
ceiling Double ceiling(value:Double) ceiling($event.value.Double) Devuelve el valor entero más pequeño que es mayor o igual que el número de punto flotante de precisión doble.
floor Double floor(value:Double) floor($event.value.Double) Devuelve el valor entero más grande que es menor o igual que el número de punto flotante de precisión doble.

Funciones trigonométricas

Nombre de función Firma Ejemplo Notas
cos Double cos(value:Double) cos($event.value.Double) Devuelve el coseno del ángulo especificado en radianes.
sin Double sin(value:Double) sin($event.value.Double) Devuelve el seno del ángulo especificado en radianes.
tan Double tan(value:Double) tan($event.value.Double) Devuelve la tangente del ángulo especificado en radianes.
acos Double acos(value:Double) acos($event.value.Double) Devuelve el ángulo en radianes cuyo coseno es el número especificado.
asin Double asin(value:Double) asin($event.value.Double) Devuelve el ángulo en radianes cuyo seno es el número especificado.
atan Double atan(value:Double) atan($event.value.Double) Devuelve el ángulo en radianes cuya tangente es el número especificado.
atan2 Double atan2(value1:Double, value2:Double) atan2($event.value1.Double, $event.value2.Double) Devuelve el ángulo en radianes cuya tangente es el cociente de dos números especificados.

Funciones logarítmicas

Nombre de función Firma Ejemplo Notas
log Double log(value:Double) log($event.value.Double) Devuelve el logaritmo natural de un número especificado.
log2 Double log2(value:Double) log2($event.value.Double) Devuelve el logaritmo en base 2 de un número especificado.
log10 Double log10(value:Double) log10($event.value.Double) Devuelve el logaritmo en base 10 de un número especificado.

Funciones de fecha y hora

Nombre de función Firma Ejemplo Notas
monthOfYear Long monthOfYear(value:DateTime) monthOfYear($event.$ts) Devuelve el mes del año como un valor numérico para la fecha y hora proporcionada.
dayOfMonth Long dayOfMonth(value:DateTime) dayOfMonth($event.$ts) Devuelve el día del mes como un valor numérico para la fecha y hora proporcionada.
hourOfDay Long hourOfDay(value:DateTime) hourOfDay($event.$ts) Devuelve la hora del día como un valor numérico para la fecha y hora proporcionada.
utcNow DateTime utcNow() utcNow() Devuelve la hora actual en formato UTC.

Funciones de cadena

Nombre de función Firma Ejemplo Notas
toUpper String toUpper(value:String) toUpper($event.value.String) Devuelve la cadena de entrada convertida en mayúsculas.
toLower String toLower(value:String) toLower($event.value.String) Devuelve la cadena de entrada convertida en minúsculas.
strLen Long strLen(value:String) strLen($event.value.String) Devuelve el número de caracteres del argumento string.
strCat Long strCat(value1:String, value2:String) strCat($event.value1.String, $event.value2.String) Concatena dos cadenas de entrada especificadas.
subString String subString(value:String, startIndex:Double, length:Double) subString($event.value.String, 2.0, 4.0) Recupera una subcadena de la instancia.
trim String trim(value:String) trim($event.value.String) Devuelve una nueva cadena quitando todos los caracteres de espacio en blanco iniciales y finales de la cadena de entrada.
indexOf Long indexOf(value:String, subString:String) indexOf($event.value.String, 'abc') Devuelve la primera aparición de la cadena especificada dentro de la cadena original, en función de la indexación cero.
replace String replace(value:String, searchString:String, replaceString:String) replace($event.value.String, 'abc', 'xyz') Devuelve una cadena en la que todas las apariciones de la cadena de búsqueda se reemplazan por la cadena de reemplazo.

Otras funciones

Nombre de función Firma Ejemplo Notas
coalesce String, Long, Double, Bool coalesce (value: String, Long, Double, Bool) coalesce(toLong($event.value.Double), $event.value.Long) Devuelve el primer valor distinto de NULL de la lista de argumentos. Acepta al menos 2 y al máximo 64 argumentos, pero todos deben ser del mismo tipo de datos.
iff String, Long, Double, Bool iff (predicate: bool, ifTrue: String, Long, Double, Bool, ifFalse: String, Long, Double, Bool) iff ($event.value.Double > 100, 'Good', 'Bad') Devuelve el segundo o tercer argumento en función de si el predicado resuelto en true (devuelve el segundo argumento) o false (devuelve el tercer argumento). El predicado debe ser una expresión booleana y los argumentos segundo y tercero deben ser del mismo tipo.

Consulte también

  • Para más información sobre el registro de aplicaciones y el modelo de programación de Azure Active Directory, consulte Azure Active Directory para desarrolladores.

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

  • Entre las herramientas que ayudan a probar las solicitudes HTTP y las respuestas se incluyen:

  • Fiddler. Este proxy de depuración web gratuito puede interceptar las solicitudes REST, por lo que puede diagnosticar los mensajes de solicitud y respuesta HTTP.

  • JWT.io. Puede usar esta herramienta para volcar rápidamente las notificaciones en el token de portador y, a continuación, validar su contenido.

  • Postman. Se trata de una herramienta gratuita de prueba de solicitudes y respuestas HTTP para depurar las API REST.

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