Функции переменных

Операции с активными листами и словарями

Функции active_list и active_list_dyn

Функции позволяют получать информацию из активного листа и динамически формировать имя поля активного листа и ключа.

Необходимо указать параметры в следующей последовательности:

1. Название активного листа.
2. Выражение, возвращающее название поля активного листа.
3. Одно или несколько выражений, из результатов которых будет составлен ключ.

   Пример использования	Результат выполнения
   active_list('Test', to_lower('DeviceHostName'), to_lower(DeviceCustomString2), to_lower(DeviceCustomString1))	Получение значения поля активного листа.

С помощью этих функций из переменной можно обратиться к активному листу общего тенанта. Для этого после названия активного листа необходимо добавить суффикс @Shared (регистр имеет значение). Например, active_list('exampleActiveList@Shared', 'score', SourceAddress, SourceUserName).

Функция table_dict

Получение информации о значении в указанном столбце словаря типа таблица.

Необходимо указать параметры в следующей последовательности:

1. Название словаря.
2. Название столбца словаря.
3. Одно или несколько выражений, из результатов которых будет составлен ключ строки словаря.

   Пример использования	Результат выполнения
   table_dict('exampleTableDict', 'office', SourceUserName)	Получение данных из словаря exampleTableDict из строки с ключом SourceUserName из столбца office.
   table_dict('exampleTableDict', 'office', SourceAddress, to_lower(SourceUserName))	Получение данных из словаря exampleTableDict из строки с составным ключом из значения поля SourceAddress и значения поля SourceUserName в нижнем регистре из столбца office.

С помощью этой функции из переменной можно обратиться к словарю общего тенанта. Для этого после названия активного листа необходимо добавить суффикс @Shared (регистр имеет значение). Например, table_dict('exampleTableDict@Shared', 'office', SourceUserName).

Функция dict

Получение информации о значении в указанном столбце словаря типа словарь.

Необходимо указать параметры в следующей последовательности:

1. Название словаря.
2. Одно или несколько выражений, из результатов которых будет составлен ключ строки словаря.

   Пример использования	Результат выполнения
   dict('exampleDictionary', SourceAddress)	Получение данных из словаря exampleDictionary из строки с ключом SourceAddress.
   dict('exampleDictionary', SourceAddress, to_lower(SourceUserName))	Получение данных из словаря exampleDictionary из строки с составным ключом из значения поля SourceAddress и значения поля SourceUserName в нижнем регистре.

С помощью этой функции из переменной можно обратиться к словарю общего тенанта. Для этого после названия активного листа необходимо добавить суффикс @Shared (регистр имеет значение). Например, dict('exampleDictionary@Shared', SourceAddress).

Операции с контекстными таблицами

Функция context_table

Возвращает значение указанного поля в базовом типе (например, целое число,массив целых чисел).

Необходимо указать параметры в следующей последовательности:

1. Название контекстной таблицы. Название не должно быть пустым.
2. Выражение, возвращающее название поля контекстной таблицы.
3. Выражение, возвращающее название ключевого поля 1 контекстной таблицы.
4. Выражение, возвращающее значение ключевого поля 1 контекстной таблицы.

Функция должна содержать минимум 4 параметра.

Функция len

Возвращает длину строки и массива.

Функция возвращает длину массива, если переданный массив соответствует следующему типу:

• массив целых чисел;
• массив чисел с плавающей точкой;
• массив строк;
• массив логических типов.

Если передан массив другого типа, данные массива приводятся к строковому типу, и функция возвращает длину полученной строки.

Функция distinct_items

Возвращает список уникальных элементов массива.

Функция возвращает список уникальных элементов массива, если переданный массив соответствует следующему типу:

• массив целых чисел;
• массив чисел с плавающей точкой;
• массив строк;
• массив логических типов.

Если передан массив другого типа, данные массива приводятся к строковому типу, и функция возвращает строку, состоящую из уникальных символов исходной строки.

Функция sort_items

Возвращает отсортированный список элементов массива.

Необходимо указать параметры в следующей последовательности:

1. Выражение, возвращающее объект сортировки.
2. Сортировка возможных значений: asc, desc. Если параметр не указан, значение по умолчанию – asc.

Функция возвращает отсортированный список элементов массива, если переданный массив соответствует следующему типу:

• массив целых чисел;
• массив чисел с плавающей точкой;
• массив строк.

Функция возвращает список элементов массива в исходном порядке, если был передан массив логических типов.

Если передан массив другого типа, данные массива приводятся к строковому типу, и функция возвращает строку отсортированных символов.

Функция item

Возвращает элемент массива с указанным индексом или символ строки с указанным индексом, если передан массив целых чисел, чисел с плавающей точкой, строк или булевых значений.

Необходимо указать параметры в следующей последовательности:

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

Функция должна содержать минимум 2 параметра.

Функция возвращает элемент массива с указанным индексом или символ строки с указанным индексом, если индекс находится в диапазоне массива и переданный массив соответствует следующему типу:

• массив целых чисел;
• массив чисел с плавающей точкой;
• массив строк;
• массив логических типов.

Если передан массив другого типа и индекс находится в диапазоне массива, данные приводятся к строковому типу и функция возвращает символ строки по индексу. Если передан массив другого типа и индекс не находится в диапазоне массива, функция возвращает пустую строку.

Операции со строками

Функция to_lower

Перевод символов в строке в нижний регистр. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

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

Функция to_upper

Перевод символов в строке в верхний регистр. Поддерживается для стандартных полей и полей расширенной схемы событий типа string. Строку можно передать строкой, названием поля или переменной.

Функция append

Добавление символов в конец строки. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Добавляемая строка.

Строки можно передать строкой, названием поля или переменной.

Функция prepend

Добавление символов в начало строки. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Добавляемая строка.

Строки можно передать строкой, названием поля или переменной.

Функция substring

Возвращает подстроку из строки. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Позиция начала подстроки (натуральное число или 0).
3. Позиция конца подстроки (необязательно).

Строки можно передать строкой, названием поля или переменной. Если номер позиции больше, чем длина строки исходных данных, возвращается пустая строка.

Функция index_of

Функция index_of возвращает байтовое смещение символа или подстроки в строке, расчет индекса начинается с 0. Если в результате работы функции подстрока не была найдена, функция вернет отрицательное значение.

Если в строке есть символы, не входящие в набор ASCII, то возвращаемое байтовое смещение не будет соответствовать количеству букв до искомой подстроки.

Доступны следующие параметры функции:

• В качестве исходных данных – поле события, другая переменная или константа.
• Любое выражение, которое доступно в локальных переменных.

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

1. Символ или подстрока, позиция которой будет найдена.
2. Строка, по которой будет осуществлен поиск.

Функция last_index_of

Функция last_index_of возвращает последнюю позицию символа или подстроки в строке, расчет индекса начинается с 0. Если в результате работы функции подстрока не была найдена, функция вернет значение -9223372036854775808.

Доступны следующие параметры функции:

• В качестве исходных данных – поле события, другая переменная или константа.
• Любое выражение, которое доступно в локальных переменных.

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

1. Символ или подстрока, позиция которой будет найдена.
2. Строка, по которой будет осуществлен поиск.

Функция tr

Убирает из начала и конца строки указанные символы. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Строка, которую следует удалить из начала и конца исходной строки (необязательно).

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

Функция replace

Заменяет все вхождения последовательности символов А в строке на последовательность символов В. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Строка поиска: последовательность символов, подлежащая замене.
3. Строка замены: последовательность символов, на которую необходимо заменить строку поиска.

Строки можно передать выражением.

Функция regexp_replace

Замена в строке последовательности символов, удовлетворяющих регулярному выражению, на последовательность символов и группы захвата регулярного выражения. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Строка поиска: регулярное выражение.
3. Строка замены: последовательность символов, на которую необходимо заменить строку поиска, и идентификаторы групп захвата регулярного выражения. Строку можно передать выражением.

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

В регулярных выражениях, используемых в функциях переменных, каждый символ обратной косой черты необходимо дополнительно экранировать. Например, вместо регулярного выражения ^example\\ необходимо указывать выражение ^example\\\\.

Функция regexp_capture

Получение из исходной строки результата, удовлетворяющего условию регулярного выражения. Поддерживается для стандартных полей и полей расширенной схемы событий типа string.

Необходимо указать параметры в следующей последовательности:

1. Исходная строка.
2. Строка поиска: регулярное выражение.

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

В регулярных выражениях, используемых в функциях переменных, каждый символ обратной косой черты необходимо дополнительно экранировать. Например, вместо регулярного выражения ^example\\ необходимо указывать выражение ^example\\\\.

Функция template

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

• Внутри строки.
• После строки. В этом случае необходимо в строке указать переменные типа {{index.<n>}}, где <n> – это индекс переменной после строки. Индекс начинается с 0.

  Примеры использования

  template('текст со значениями полей события rule={{.DeviceCustomString1}} и {{.Name}}, а также значениями локальных переменных {{index.0}} и {{index.1}} и {{index.2}}', $var1, $var2, $var10)

Операции с метками времени

Функция now

Получение временной метки в формате epoch. Запускается без аргументов.

Функция extract_from_timestamp

Получение атомарных представлений времени (в виде год, месяц, день, час, минута, секунда, день недели) из полей и переменных с временем в формате epoch.

Параметры необходимо указать в следующей последовательности:

1. Поле события, имеющего тип timestamp, или переменная.
2. Обозначение атомарного представления времени. Параметр регистрозависимый.

   Возможные варианты обозначения атомарного времени:

   • y – год в виде числа.
   • M – месяц, числовое обозначение.
   • d – число месяца.
   • wd – день недели: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.
   • h – часы в 24-часовом формате.
   • m – минуты.
   • s – секунды.
3. Обозначение часового пояса (необязательно).

   Параметр может быть указан как строка (например, Европа / Москва) или как переменная ($timezone). Переменная должна быть объявлена в локальных переменных правила корреляции. Значение переменной должно содержать строковый идентификатор часового пояса. Также разрешено использовать переменные, производные от других переменных и значений словаря.

   Если параметр не указан, время высчитывается в формате UTC.

   Примеры использования

   extract_from_timestamp(Timestamp, 'wd')

   extract_from_timestamp(Timestamp, 'h')

   extract_from_timestamp($otherVariable, 'h')

   extract_from_timestamp(Timestamp, 'h', 'Europe/Moscow')

   extract_from_timestamp(Timestamp, 'h', $timezone)

В этом примере переменная $timezone является производной от другой переменной и значения словаря и используется в качестве параметра timezone.

Функция parse_timestamp

Представление времени из формата RFC3339 (например, 2022-05-24 00:00:00, 2022-05-24 00:00:00+0300) в формат epoch.

Функция format_timestamp

Представление времени из формата epoch в формат RFC3339.

Параметры необходимо указать в следующей последовательности:

1. Поле события, имеющего тип timestamp, или переменная.
2. Обозначение формата времени: RFC3339.
3. Обозначение часового пояса (необязательно). Если параметр не указан, время высчитывается в формате UTC.

   Примеры использования

   format_timestamp(Timestamp, 'RFC3339')

   format_timestamp($otherVariable, 'RFC3339')

   format_timestamp(Timestamp, 'RFC3339', 'Europe/Moscow')

Функция truncate_timestamp

Округление времени в формате epoch. После округления время возвращается в формате epoch. Время округляется в меньшую сторону.

Параметры необходимо указать в следующей последовательности:

1. Поле события, имеющего тип timestamp, или переменная.
2. Параметр округления:
   • 1s – округление до секунд;
   • 1m – округление до минут;
   • 1h – округление до часов;
   • 24h – округление до суток.
3. Обозначение часового пояса (необязательно). Если параметр не указан, время высчитывается в формате UTC.

   Примеры использования	Примеры округляемых значений	Результат использования
   truncate_timestamp(Timestamp, '1m')	1654631774175 (7 June 2022 г., 19:56:14.175)	1654631760000 (7 June 2022 г., 19:56:00)
   truncate_timestamp($otherVariable, '1h')	1654631774175 (7 June 2022 г., 19:56:14.175)	1654628400000 (7 June 2022 г., 19:00:00)
   truncate_timestamp(Timestamp, '24h', 'Europe/Moscow')	1654631774175 (7 June 2022 г., 19:56:14.175)	1654560000000 (7 June 2022 г., 0:00:00)

Функция time_diff

Получение интервала времени между двумя метками времени в формате epoch.

Параметры необходимо указать в следующей последовательности:

1. Время конца отрезка. Поле события, имеющего тип timestamp, или переменная.
2. Время начала отрезка. Поле события, имеющего тип timestamp, или переменная.
3. Представление временного интервала:
   • ms – в миллисекундах;
   • s – в секундах;
   • m – в минутах;
   • h – в часах;
   • d – в днях.

   Примеры использования

   time_diff(EndTime, StartTime, 's')

   time_diff($otherVariable, Timestamp, 'h')

   time_diff(Timestamp, DeviceReceiptTime, 'd')

Математические операции

Представлены как простейшими математическими операциями, так и функциями.

Простейшие математические операции

Поддерживаются для полей расширенной схемы событий с типом "целое число" и "число с плавающей точкой".

Операции:

• сложение;
• вычитание;
• умножение;
• деление;
• деление по модулю.

Использование круглых скобок определяет последовательность действий

Доступные аргументы:

• числовые поля события;
• числовые переменные;
• вещественные числа.

  При делении по модулю в качестве аргументов можно использовать только натуральные числа.

Ограничения использования:

• Деление на ноль возвращает ноль.
• Математические операции между числами и строками возвращают число в неизменном виде. Например, "1 + abc" вернет 1.
• Целые числа, полученные в результате операций, возвращаются без точки.

  Примеры использования (Type=3; otherVariable=2; Message=text)	Результат использования
  Type + 1	4
  $otherVariable - Type	-1
  2 * 2.5	5
  2 / 0	0
  Type * Message	0
  (Type + 2) * 2	10
  Type % $otherVariable	1

Функция round

Округление чисел. Поддерживаются для полей расширенной схемы событий с типом "целое число" и "число с плавающей точкой".

Доступные аргументы:

• числовые поля события;
• числовые переменные;
• числовые константы.

  Примеры использования (DeviceCustomFloatingPoint1=7.75; DeviceCustomFloatingPoint2=7.5 otherVariable=7.2)	Результат использования
  round(DeviceCustomFloatingPoint1)	8
  round(DeviceCustomFloatingPoint2)	8
  round($otherVariable)	7

Функция ceil

Округление чисел в большую сторону. Поддерживаются для полей расширенной схемы событий с типом "целое число" и "число с плавающей точкой".

Доступные аргументы:

• числовые поля события;
• числовые переменные;
• числовые константы.

  Примеры использования (DeviceCustomFloatingPoint1=7.15; otherVariable=8.2)	Результат использования
  ceil(DeviceCustomFloatingPoint1)	8
  ceil($otherVariable)	9

Функция floor

Округление чисел в меньшую сторону. Поддерживаются для полей расширенной схемы событий с типом "целое число" и "число с плавающей точкой".

Доступные аргументы:

• числовые поля события;
• числовые переменные;
• числовые константы.

  Примеры использования (DeviceCustomFloatingPoint1=7.15; otherVariable=8.2)	Результат использования
  floor(DeviceCustomFloatingPoint1)	7
  floor($otherVariable)	8

Функция abs

Получение числа по модулю. Поддерживаются для полей расширенной схемы событий с типом "целое число" и "число с плавающей точкой".

Доступные аргументы:

• числовые поля события;
• числовые переменные;
• числовые константы.

  Примеры использования (DeviceCustomNumber1=-7; otherVariable=-2)	Результат использования
  abs(DeviceCustomFloatingPoint1)	7
  abs($otherVariable)	2

Функция pow

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

Параметры необходимо указать в следующей последовательности:

1. База – вещественные числа.
2. Степень – натуральные числа.

Доступные аргументы:

• числовые поля события;
• числовые переменные;
• числовые константы.

  Примеры использования

  pow(DeviceCustomNumber1, DeviceCustomNumber2)

  pow($otherVariable, DeviceCustomNumber1)

Функция str_join

Позволяет объединить несколько строк в одну с использованием разделителя. Поддерживаются для полей расширенной схемы событий с типом "целое число" и "число с плавающей точкой".

Параметры необходимо указать в следующей последовательности:

1. Разделитель. Строка.
2. Строка1, строка2, строкаN. Минимум 2 выражения.

   Примеры использования	Результат использования
   str_join('|', to_lower(Name), to_upper(Name), Name)	Строка.

Функция conditional

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

Параметры необходимо указать в следующей последовательности:

1. Условие. Строка. Синтаксис аналогичен условиям в SQL Where. В условии можно использовать функции переменных KUMA и ссылаться на другие переменные.
2. Значение при выполнении условия. Выражение.
3. Значение при невыполнении условия. Выражение.

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

• AND
• OR
• NOT
• =
• !=
• <
• <=
• >
• >=
• LIKE (передается регулярное выражение RE2, а не SQL-выражение)
• ILIKE (передается регулярное выражение RE2, а не SQL-выражение)
• BETWEEN
• IN
• IS NULL (проверка на пустое значение, например 0 или пустую строку)

  Примеры использования (значение зависит от аргументов 2 и 3)

  conditional('SourceUserName = \\'root\\' AND DestinationUserName = SourceUserName', 'match', 'no match')

  conditional(`DestinationUserName ILIKE 'svc_.*'`, 'match', 'no match')

  conditional(`DestinationUserName NOT LIKE 'svc_.*'`, 'match', 'no match')

Операции для полей расширенной схемы событий

Для полей расширенной схемы событий типа строка поддерживаются следующие виды операций:

• Функция len
• Функция to_lower
• Функция to_upper
• Функция append
• Функция prepend
• Функция substring
• Функция tr
• Функция replace
• Функция regexp_replace
• Функция regexp_capture

Для полей расширенной схемы событий с типом "целое число" или "число с плавающей точкой" поддерживаются следующие виды операций:

• Простые математические операции:
• Функция round
• Функция ceil
• Функция floor
• Функция abs
• Функция pow
• Функция str_join
• Функция conditional

KUMA поддерживает для полей расширенной схемы событий с типом массив целых чисел, массив чисел с плавающей точкой и массив строк следующие виды функций:

• Получение i-го элемента массива. Пример: item(<type>.someStringArray).
• Получение массива значений. Пример: <type>.someStringArray. Вернет ["string1", "string2", "string3"].
• Получение количества элементов в массиве. Пример: len(<type>.someStringArray). Вернет ["string1", "string2"].
• Получение уникальных записей из массива. Пример: distinct_items(<type>.someStringArray).
• Формирование строки с элементами массива в формате TSV. Пример: to_string(<type>.someStringArray).
• Сортировка элементов массива. Пример: sort_items(<type>.someStringArray).

  В примерах вместо <type> необходимо указать тип массива: NA для массива целых чисел, FA для массива чисел с плавающей точкой, SA для массива строк.

Для полей с типом массив целых чисел и массив чисел с плавающей точкой поддерживаются следующие функции:

• math_min – возвращает минимальный элемент массива. Пример: math_min(NA.NumberArray), math_min(FA.FloatArray).
• math_max – возвращает максимальный элемент массива. Пример: math_max(NA.NumberArray), math_max(FA.FloatArray).
• math_avg – возвращает среднее значение массива. Пример: math_avg(NA.NumberArray), math_avg(FA.FloatArray).