Синтаксис выражения временных рядов Аналитика временных рядов Azure 2-го поколения

Статья
07/19/2023

Общие сведения

Выражение временных рядов (TSX) — это язык выражений на основе строк с строгой типизированием. TSX используется для представления следующих сущностей в запросе временных рядов.

Фильтр
Значение
Агрегирование

Выражения фильтра

Выражения фильтра используются для представления логических предложений. В следующей таблице перечислены примеры фильтров:

TSX	Описание
`$event.PointValue.Double = 3.14`	`true` для событий с параметром double PointValue , равным `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true`для событий с pointValue больше и строковым состоянием `3.14Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` для событий с меткой времени больше `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` для событий с параметром PointValue , равным `true`

Выражения значений

Выражения значений используются для обозначения значения для числовых и категориальных переменных. Выражение значения может быть выражением ссылки на свойство типа Double или Long.

Пример:

TSX	Примечания
`$event.Temperature.Double`	Последний маркер в любом выражении значения (в данном случае `Double`) считывается как Тип свойства .
`$event.Temperature`	Предполагается, что для свойства, доступ к которым осуществляется из одного маркера, используется тип Double .
`$event['Temperature-Celsius']`	Используйте `[` и `]` для экранирования маркеров, имеющих специальные символы. Кроме того, используйте `\` в квадратных скобках, чтобы экранировать следующие символы: `\` и `'`.
`$event.Temperature.Celsius.Double`	Используйте `.` для доступа к вложенным свойствам. При доступе к вложенным свойствам требуется тип.
`$event.Temperature['Celsius-C'].Double`	Используйте `[` и `]` для экранирования маркеров, которые имеют специальные символы при доступе к вложенным свойствам. Кроме того, используйте `\` в квадратных скобках, чтобы экранировать следующие символы: `\` и `'`. При доступе к вложенным свойствам требуется тип.
`$event['Temperature']['Celsius'].Double`	`[` Использование и `]` для экранирования маркеров разрешено для любого маркера.

Тип числовых переменных

Результат выражения значения должен иметь тип Double или Long .

Тип агрегатной переменной

Результат выражения значения может иметь любые поддерживаемые типы.

Тип категориальной переменной

Результатом выражения значения может быть только тип String или Long .

Статистические выражения

Статистические выражения используются для описания операции агрегирования, используемой в запросе. Статистическое выражение приводит к одному значению для каждого интервала. Статистические выражения можно применять к числовым и агрегатным переменным.

Выражения агрегирования — тип числовых переменных

Числовые переменные должны ссылаться на $value.

Ниже приведены поддерживаемые агрегатные функции.

Агрегатная функция	Пример	Описание
`min`	`min($value)`	Вычисляет минимальное значение интервала `$value` . Избегает значений `null` . Не может использоваться с интерполяцией.
`max`	`max($value)`	Вычисляет максимальное значение интервала `$value` . Избегает значений `null` . Не может использоваться с интерполяцией.
`sum`	`sum($value)`	Вычисляет сумму `$value` по всем событиям в интервале. Избегает значений `null` . Не может использоваться с интерполяцией.
`avg`	`avg($value)`	Вычисляет среднее значение `$value` по всем событиям в интервале. Избегает значений `null` . Не может использоваться с интерполяцией.
`first`	`first($value)`	Возвращает `$value` первое событие в интервале по метке времени события. Не избегает `null` значений. Не может использоваться с интерполяцией.
`last`	`last($value)`	Возвращает `$value` последнее событие в интервале по метке времени события. Не избегает `null` значений. Не может использоваться с интерполяцией.
`median`	`median($value)`	Возвращает `$value` среднее событие в интервале по метке времени события. Не избегает `null` значений. Не может использоваться с интерполяцией.
`stdev`	`stdev($value)`	Возвращает `$value` стандартное отклонение событий в интервале. Избегает значений `null` . Не может использоваться с интерполяцией.
`twsum`	`twsum($value)`	Возвращает `$value` взвешаемую по времени сумму событий в интервале. Требует интерполяции.
`twavg`	`twavg($value)`	Возвращает `$value` среднее взвешенный по времени для событий в интервале. Требует интерполяции.
`left`	`left($value)`	Возвращает в `$value` левом крае заданного интервала. Требует интерполяции.
`right`	`right($value)`	Возвращает объект в `$value` правом крае заданного интервала. Требует интерполяции.

Агрегирование выражений — тип агрегатной переменной

Агрегатные переменные должны ссылаться на свойство в полезных данных события.

Ниже приведены поддерживаемые агрегатные функции.

Агрегатная функция	Пример	Описание
`count`	`count()`	Возвращает количество событий за интервал.
`min`	`min($event.Temperature.Double)`	Вычисляет минимальное значение свойства Temperature на интервал. Избегает значений `null` .
`max`	`max($event.Temperature.Long)`	Вычисляет максимальное значение свойства Temperature на интервал. Избегает значений `null` .
`sum`	`sum($event.Temperature.Double)`	Вычисляет сумму свойства Temperature по всем событиям в интервале. Избегает значений `null` .
`avg`	`avg($event.Temperature.Long)`	Вычисляет среднее значение свойства Temperature для всех событий в интервале. Избегает значений `null` .
`first`	`first($event.Temperature.String)`	Возвращает первое возникающее (по метке времени события) значение свойства Temperature из всех событий в интервале. Не избегает `null` значений.
`last`	`last($event.Temperature.String)`	Возвращает последнее возникающее (по метке времени события) значение свойства Temperature из всех событий в интервале. Не избегает `null` значений.
`median`	`median($event.Temperature.String)`	Возвращает среднее значение (по метке времени события) свойства Temperature из всех событий в интервале. Не избегает `null` значений.
`stdev`	`stdev($event.Temperature.String)`	Вычисляет стандартное отклонение свойства Температура на интервал. Избегает значений `null` .

Для агрегатного типа переменной эти функции можно объединить в агрегатное выражение. Например: max($event.Temperature.Long) - min($event.Temperature.Long).

Синтаксис

В этом разделе описываются основные понятия синтаксиса и операторы запросов, объединенные в выражения формы.

Поддерживаемые литералы

Примечание

Приведенные ниже литералы используются для формирования выражений. Полный список типов данных см. в статье Поддерживаемые типы данных.

Тип-примитив	Литералы
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`

Поддерживаемые типы операндов

Операция	Поддерживаемые типы	Примечания
<, >, <=, >=	Double, Long, DateTime, TimeSpan
=, !=, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> эквивалентно !=
+, -, *, /	Double, Long, DateTime, TimeSpan

Для выражений сравнения (<, >, <=, >=, =, !=) операнды могут иметь значение NULL или иметь один и тот же тип. В каждом выражении предиката типы операндов левой части (LHS) и правой части (RHS) проверяются на соответствие. Ошибки возникают, если типы LHS и RHS не согласны или операция не разрешена для определенных типов.

Примечание

Строковый тип не допускает значения NULL в теплом хранилище:

Сравнение string с null и пустой строкой ('') ведет себя одинаково: $event.p1.String = NULL эквивалентно $event.p1.String = ''.
API может возвращать значения NULL , даже если исходные события содержали пустые строки.

В будущем такое же поведение будет выполняться в холодном хранилище.

Не следует принимать зависимости от значений NULL в столбцах String и обрабатывать их так же, как пустые строки.

Применяется проверка типа:
- Любой тип свойства принимается для литерала NULL .
- Типы LHS и RHS должны совпадать.

Ниже приведены примеры свойств p1 и p2 типа String, свойства p3 типа Double и вложенного свойства, хранящегося как p4.p5 типа Double:

Фильтр	Является ли допустимым?	Примечания
`$event.p1.String = 'abc'`	Да
`$event.p1.String = $event.p2.String`	Да
`$event.p1.String = NULL`	Да	`NULL` соответствует любому типу слева.
`$event.p3.Double = 'abc'`	Нет	Несоответствие типов.
`$event.p3.Double = $event.p1.String`	Нет	Несоответствие типов.
`$event.p1 = 'abc'`	Нет	Несоответствие типов.
`$event.p1 = 1`	Нет	Несоответствие типов.
`$event.p1 = true`	Нет	Несоответствие типов.
`$event.p1 = NULL`	Да	`p1` — это единственный используемый маркер. Интерпретируется как `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Да	`['p1']` — это единственный используемый маркер. Интерпретируется как `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	Нет	Недопустимый синтаксис ссылки на свойство. Тип должен быть указан в LHS сравнения.
`$event.p4.p5.Double = 0.0`	Да

Поддерживаемые скалярные функции

Ниже приведен список скалярных функций по категориям:

Функции преобразования

Имя функции	Сигнатура	Пример	Примечания
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Преобразует аргументы в Double.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Преобразует аргументы в long.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Преобразует аргументы в String.

Математические функции

Имя функции	Сигнатура	Пример	Примечания
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Округляет число двойной точности с плавающей точкой до ближайшего целого.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Возвращает наименьшее целочисленное значение, которое больше или равно числу двойной точности с плавающей запятой.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Возвращает наибольшее целочисленное значение, которое меньше или равно числу двойной точности с плавающей запятой.

Тригонометрические функции

Имя функции	Сигнатура	Пример	Примечания
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Возвращает косиус указанного угла в радианах.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Возвращает синус указанного угла в радианах.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Возвращает тангенс указанного угла в радианах.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Возвращает угол в радианах, косисинус которых является указанным числом.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Возвращает угол в радианах, синус которых является указанным числом.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Возвращает угол в радианах, тангенс которого является указанным числом.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Возвращает угол в радианах, тангенс которого является частной частью двух указанных чисел.

Логарифмические функции

Имя функции	Сигнатура	Пример	Примечания
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Возвращает натуральный логарифм указанного числа.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Возвращает логарифм с основанием 2 указанного числа.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Возвращает логарифм с основанием 10 указанного числа.

Функции даты и времени

Имя функции	Сигнатура	Пример	Примечания
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Возвращает месяц года в виде числа для указанного значения DateTime.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Возвращает день месяца в виде числа для указанного значения DateTime.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Возвращает час дня в виде числового значения для предоставленного значения DateTime.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Возвращает текущее время в формате UTC.

Строковые функции

Имя функции	Сигнатура	Пример	Примечания
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Возвращает входную строку, преобразованную в верхний регистр.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Возвращает входную строку, преобразованную в нижний регистр.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Возвращает количество символов в строковом аргументе.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Объединяет две указанные входные строки.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Извлекает подстроку из данного экземпляра.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Возвращает новую строку, удалив из входной строки все начальные и конечные пробелы.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Возвращает первое вхождение указанной строки в исходной строке на основе нулевого индексирования.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Возвращает строку, в которой все вхождения строки поиска заменяются строкой замены.

Прочие функции

Имя функции	Сигнатура	Пример	Примечания
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Возвращает первое значение, отличное от NULL, в списке аргументов. Принимает не менее 2 аргументов и не более 64 аргументов, но все они должны иметь один и тот же тип данных.
`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')`	Возвращает второй или третий аргумент в зависимости от того, разрешен ли предикат в значение true (возвращает второй аргумент) или false (возвращает третий аргумент). Предикат должен быть логическим выражением, а второй и третий аргументы должны иметь один и тот же тип.

См. также раздел

Дополнительные сведения о регистрации приложений и модели программирования Azure Active Directory см. в статье Azure Active Directory для разработчиков.
Дополнительные сведения о параметрах запроса и проверки подлинности см. в статье Проверка подлинности и авторизация.
Ниже представлены средства, помогающие тестировать HTTP-запросы и ответы.
Фиддлер. Этот бесплатный прокси-сервер веб-отладки может перехватывать запросы REST, чтобы можно было диагностировать HTTP-запросы и ответные сообщения.
JWT.io. Это средство можно использовать для быстрого дампа утверждений в маркере носителя, а затем для проверки их содержимого.
Postman. Это бесплатное средство тестирования HTTP-запросов и ответов для отладки REST API.
Дополнительные сведения о Аналитика временных рядов Azure 2-го поколения см. в документации 2-го поколения.

Поделиться через