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

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

Функции "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 параметра.

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

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

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

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

Функция "len"

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

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

Функция "to_lower"

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

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

Функция "to_upper"

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

Функция "append"

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

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

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

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

Функция "prepend"

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

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

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

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

Функция "substring"

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

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

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

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

Функция "index_of"

Функция "index_of" возвращает первую позицию символа или подстроки в строке, расчет индекса начинается с 0.

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

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

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

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

Функция "last_index_of"

Функция "last_index_of" возвращает последнюю позицию символа или подстроки в строке, расчет индекса начинается с 0.

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

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

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

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

Функция "tr"

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

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

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

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

Функция "replace"

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

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

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

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

Функция "regexp_replace"

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

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

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

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

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

Функция "regexp_capture"

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

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

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

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

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

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

Функция 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. (необязательно) Обозначение часового пояса. Если параметр не указан, время высчитывается в формате UTC.

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

   extract_from_timestamp(Timestamp, 'wd')

   extract_from_timestamp(Timestamp, 'h')

   extract_from_timestamp($otherVariable, 'h')

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

Функция "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)