Functions of variables

Operations with active lists and dictionaries

active_list and active_list_dyn

These functions allow you to receive information from an active list and dynamically generate a field name for an active list and key.

You must specify the parameters in the following sequence:

1. Name of the active list
2. Expression that returns the field name of the active list
3. One or more expressions whose results are used to generate the key

   Usage example	Result
   active_list('Test', to_lower('DeviceHostName'), to_lower(DeviceCustomString2), to_lower(DeviceCustomString1))	Gets the field value of the active list.

You can use these functions to reference an active list of the Shared tenant from a variable. To do so, add the @Shared suffix after the name of the active list (case sensitive). For example, active_list('exampleActiveList@Shared', 'score', SourceAddress, SourceUserName).

table_dict

Gets information about the value in the specified column of a dictionary of the table type.

You must specify the parameters in the following sequence:

1. Dictionary name
2. Dictionary column name
3. One or more expressions whose results are used to generate the dictionary row key.

   Usage example	Result
   table_dict('exampleTableDict', 'office', SourceUserName)	Gets data from the exampleTableDict dictionary from the row with the SourceUserName key in the office column.
   table_dict('exampleTableDict', 'office', SourceAddress, to_lower(SourceUserName))	Gets data from the exampleTableDict dictionary from a composite key string from the SourceAddress field value and the lowercase value of the SourceUserName field from the office column.

You can use this function to reference a dictionary of the Shared tenant from a variable. To do so, add the @Shared suffix after the name of the active list (case sensitive). For example, table_dict('exampleTableDict@Shared', 'office', SourceUserName).

dict

Gets information about the value in the specified column of a dictionary of the dictionary type.

You must specify the parameters in the following sequence:

1. Dictionary name
2. One or more expressions whose results are used to generate the dictionary row key.

   Usage example	Result
   dict('exampleDictionary', SourceAddress)	Gets data from exampleDictionary from the row with the SourceAddress key.
   dict('exampleDictionary', SourceAddress, to_lower(SourceUserName))	Gets data from the exampleDictionary from a composite key string from the SourceAddress field value and the lowercase value of the SourceUserName field.

You can use this function to reference a dictionary of the Shared tenant from a variable. To do so, add the @Shared suffix after the name of the active list (case sensitive). For example, dict('exampleDictionary@Shared', SourceAddress).

Operations with context tables

context_table

Returns the value of the specified field in the base type (for example, integer, array of integers).

You must specify the parameters in the following sequence:

1. Name of the context table. The name must be specified.
2. Expression that returns the field name of context table.
3. Expression that returns the name of key field 1 of the context table.
4. Expression that returns the value of key field 1 of the context table.

The function must contain at least 4 parameters.

Usage example	Result
context_table('tbl1', 'list_field1', 'key1', 'key1_val')	Get the value of the specified field. If the context table or context table field does not exist, an empty string is returned.

len

Returns the length of a string or array.

The function returns the length of the array if the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings
• array of booleans

If an array of a different type is passed, the data of the array is cast to the string type, and the function returns the length of the resulting string.

Usage examples

len(context_table('tbl1', 'list_field1', 'key1', 'key1_val'))

len(DeviceCustomString1)

distinct_items

Returns a list of unique elements in an array.

The function returns the list of unique elements of the array if the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings
• array of booleans

If an array of a different type is passed, the data of the array is cast to the string type, and the function returns a string consisting of the unique characters from the original string.

Usage examples

distinct_items(context_table('tbl1', 'list_field1', 'key1', 'key1_val'))

distinct_items(DeviceCustomString1)

sort_items

Returns a sorted list of array elements.

You must specify the parameters in the following sequence:

1. Expression that returns the object of the sorting
2. Sorting order Possible values: asc, desc. If the parameter is not specified, the default value is asc.

The function returns the list of sorted elements of the array if the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings

For a boolean array, the function returns the list of array elements in the original order.

If an array of a different type is passed, the data of the array is cast to the string type, and the function returns a string of sorted characters.

Usage examples

sort_items(context_table('tbl1', 'list_field1', 'key1', 'key1_val'), 'asc')

sort_items(DeviceCustomString1)

item

Returns the array element with the specified index or the character of a string with the specified index if an array of integers, floats, strings, or boolean values is passed.

You must specify the parameters in the following sequence:

1. Expression that returns the object of the indexing
2. Expression that returns the index of the element or character.

The function must contain at least 2 parameters.

The function returns the array element with the specified index or the string character with the specified index if the index falls within the range of the array and the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings
• array of booleans

If an array of a different type is passed and the index falls within the range of the array, the data is cast to the string type, and the function returns the string character with the specified index. If an array of a different type is passed and the index is outside the range of the array, the function returns an empty string.

Usage examples

item(context_table('tbl1', 'list_field1', 'key1', 'key1_val'), 1)

item(DeviceCustomString1, 0)

Operations with strings

to_lower

Converts characters in a string to lowercase. Supported for standard fields and extended event schema fields of the string type.

A string can be passed as a string, field name or variable.

Usage examples

to_lower(SourceUserName)

to_lower('SomeText')

to_lower($otherVariable)

to_upper

Converts characters in a string to uppercase. Supported for standard fields and extended event schema fields of the string type. A string can be passed as a string, field name or variable.

Usage examples

to_upper(SourceUserName)

to_upper('SomeText')

to_upper($otherVariable)

append

Adds characters to the end of a string. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. Added string.

Strings can be passed as a string, field name or variable.

Usage examples	Usage result
append(Message, '123')	The string 123 is added to the end of this string from the Message field.
append($otherVariable, 'text')	The string text is added to the end of this string from the variable otherVariable.
append(Message, $otherVariable)	A string from otherVariable is added to the end of this string from the Message field.

prepend

Adds characters to the beginning of a string. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. Added string.

Strings can be passed as a string, field name or variable.

Usage examples	Usage result
prepend(Message, '123')	The string 123 is added to the beginning of this string from the Message field.
prepend($otherVariable, 'text')	The string text is added to the beginning of this string from otherVariable.
prepend(Message, $otherVariable)	A string from otherVariable is added to the beginning of this string from the Message field.

substring

Returns a substring from a string. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. Substring start position (natural number or 0).
3. (Optional) substring end position.

Strings can be passed as a string, field name or variable. If the position number is greater than the original data string length, an empty string is returned.

Usage examples	Usage result
substring(Message, 2)	Returns a part of the string from the Message field: from 3 characters to the end.
substring($otherVariable, 2, 5)	Returns a part of the string from the otherVariable variable: from 3 to 6 characters.
substring(Message, 0, len(Message) - 1)	Returns the entire string from the Message field except the last character.

index_of

The index_of function returns the byte offset of a character or substring in a string; the first character in the string has index 0. If the function does not find the substring, the function returns a negative value.

If the string has non-ASCII characters, the returned byte offset will not correspond to the number of characters preceding the substring you are searching for.

The function accepts the following parameters:

• As source data, an event field, another variable, or constant.
• Any expression out of those that are available in local variables.

To use this function, you must specify the parameters in the following order:

1. Character or substring whose position you want to find.
2. String to be searched.

Usage examples	Usage result
index_of('@', SourceUserName)	The function looks for the @ character in the SourceUserName field. The SourceUserName field contains the user@example.com string. Result = 4 The function returns the index of the first occurrence of the character in the string. The first character in the string has index 0.
index_of('m', SourceUserName)	The function looks for the m character in the SourceUserName field. The SourceUserName field contains the user@example.com string. Result = 8 The function returns the index of the first occurrence of the character in the string. The first character in the string has index 0.

last_index_of

The last_index_of function returns the position of the last occurrence of a character or substring in a string; the first character in the string has index 0. If the function does not find the substring, the function returns -922337203685477580.

The function accepts the following parameters:

• As source data, an event field, another variable, or constant.
• Any expression out of those that are available in local variables.

To use this function, you must specify the parameters in the following order:

1. Character or substring whose position you want to find.
2. String to be searched.

Usage examples	Usage result
last_index_of('m', SourceUserName)	The function looks for the m character in the SourceUserName field. The SourceUserName field contains the user@example.com string. Result = 15 The function returns the index of the last occurrence of the character in the string. The first character in the string has index 0.

tr

Deletes the specified characters from the beginning and end of a string. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. (Optional) string that should be removed from the beginning and end of the original string.

Strings can be passed as a string, field name or variable. If you do not specify a string to be deleted, spaces will be removed from the beginning and end of the original string.

Usage examples	Usage result
tr(Message)	Spaces have been removed from the beginning and end of the string from the Message field.
tr($otherVariable, '_')	If the otherVariable variable has the _test_ value, the string _test_ is returned.
tr(Message, '@example.com')	If the Message event field contains the string user@example.com, the string user is returned.

replace

Replaces all occurrences of character sequence A in a string with character sequence B. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. Search string: sequence of characters to be replaced.
3. Replacement string: sequence of characters to replace the search string.

Strings can be passed as an expression.

Usage examples	Usage result
replace(Name, 'UserA', 'UserB')	Returns a string from the Name event field in which all occurrences of UserA are replaced with UserB.
replace($otherVariable, ' text ', '_text_')	Returns a string from otherVariable in which all occurrences of ' text' are replaced with '_text_'.

regexp_replace

Replaces a sequence of characters that match a regular expression with a sequence of characters and regular expression capturing groups. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. Search string: regular expression.
3. Replacement string: sequence of characters to replace the search string, and IDs of the regular expression capturing groups. A string can be passed as an expression.

Strings can be passed as a string, field name or variable. Unnamed capturing groups can be used.

In regular expressions used in variable functions, each backslash character must be additionally escaped. For example, ^example\\\\ must be used instead of the regular expression ^example\\.

Usage examples	Usage result
regexp_replace(SourceAddress, '([0-9]{1,3}).([0-9]{1,3}).([0-9]{1,3}).([0-9]{1,3})', 'newIP: $1.$2.$3.10')	Returns a string from the SourceAddress event field in which the text newIP is inserted before the IP addresses. In addition, the last digits of the address are replaced with 10.

regexp_capture

Gets the result matching the regular expression condition from the original string. Supported for standard fields and extended event schema fields of the string type.

You must specify the parameters in the following sequence:

1. Original string.
2. Search string: regular expression.

Strings can be passed as a string, field name or variable. Unnamed capturing groups can be used.

In regular expressions used in variable functions, each backslash character must be additionally escaped. For example, ^example\\\\ must be used instead of the regular expression ^example\\.

Usage examples	Example values	Usage result
regexp_capture(Message, '(\\\\d{1,3}\\\\.\\\\d{1,3}\\\\.\\\\d{1,3}\\\\.\\\\d{1,3})')	Message = 'Access from 192.168.1.1 session 1' Message = 'Access from 45.45.45.45 translated address 192.168.1.1 session 1'	'192.168.1.1' '45.45.45.45'

template

Returns the string specified in the function, with variables replaced with their values. The template function can be used in one of two ways:

• With a single argument. In this case, you can use the field names to substitute values in the template.
• With multiple arguments. In this case, the zero-based index of the argument is used to substitute values.

  Usage examples

  template('Message text: {{.Message}}') template('Name in lower case: {{index . 0}}. Name in upper case: {{index . 1}}', to_lower(Name), to_upper(Name))

Operations with timestamps

now function

Gets a timestamp in epoch format. Runs with no arguments.

Usage examples

now()

extract_from_timestamp

Gets atomic time representations (year, month, day, hour, minute, second, day of the week) from fields and variables with time in the epoch format.

The parameters must be specified in the following sequence:

1. Event field of the timestamp type, or variable.
2. Notation of the atomic time representation. This parameter is case sensitive.

   Possible variants of atomic time notation:

   • y refers to the year in number format.
   • M refers to the month in number notation.
   • d refers to the number of the month.
   • wd refers to the day of the week: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.
   • h refers to the hour in 24-hour format.
   • m refers to the minutes.
   • s refers to the seconds.
3. (optional) Time zone notation. If this parameter is not specified, the time is calculated in UTC format.

   Usage examples

   extract_from_timestamp(Timestamp, 'wd')

   extract_from_timestamp(Timestamp, 'h')

   extract_from_timestamp($otherVariable, 'h')

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

parse_timestamp

Converts the time from RFC3339 format (for example, 2022-05-24 00:00:00, 2022-05-24 00:00:00+0300) to epoch format.

Usage examples

parse_timestamp(Message)

parse_timestamp($otherVariable)

format_timestamp

Converts the time from epoch format to RFC3339 format.

The parameters must be specified in the following sequence:

1. Event field of the timestamp type, or variable.
2. Time format notation: RFC3339.
3. (optional) Time zone notation. If this parameter is not specified, the time is calculated in UTC format.

   Usage examples

   format_timestamp(Timestamp, 'RFC3339')

   format_timestamp($otherVariable, 'RFC3339')

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

truncate_timestamp

Rounds the time in epoch format. After rounding, the time is returned in epoch format. Time is rounded down.

The parameters must be specified in the following sequence:

1. Event field of the timestamp type, or variable.
2. Rounding parameter:
   • 1s rounds to the nearest second.
   • 1m rounds to the nearest minute.
   • 1h rounds to the nearest hour.
   • 24h rounds to the nearest day.
3. (optional) Time zone notation. If this parameter is not specified, the time is calculated in UTC format.

   Usage examples	Examples of rounded values	Usage result
   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

Gets the time interval between two timestamps in epoch format.

The parameters must be specified in the following sequence:

1. Interval end time. Event field of the timestamp type, or variable.
2. Interval start time. Event field of the timestamp type, or variable.
3. Time interval notation:
   • ms refers to milliseconds.
   • s refers to seconds.
   • m refers to minutes.
   • h refers to hours.
   • d refers to days.

   Usage examples

   time_diff(EndTime, StartTime, 's')

   time_diff($otherVariable, Timestamp, 'h')

   time_diff(Timestamp, DeviceReceiptTime, 'd')

Mathematical operations

These are comprised of basic mathematical operations and functions.

Basic mathematical operations

Supported for extended event schema fields of the integer and float types.

Operations:

• Addition
• Subtraction
• Multiplication
• Division
• Modulo division

Parentheses determine the sequence of actions

Available arguments:

• Numeric event fields
• Numeric variables
• Real numbers

  When modulo dividing, only natural numbers can be used as arguments.

Usage constraints:

• Division by zero returns zero.
• Mathematical operations on a number and a strings return the number unchanged. For example, 1 + abc returns 1.
• Integers resulting from operations are returned without a dot.

  Usage examples (Type=3; otherVariable=2; Message=text)	Usage result
  Type + 1	4
  $otherVariable - Type	-1
  2 * 2.5	5
  2 / 0	0
  Type * Message	0
  (Type + 2) * 2	10
  Type % $otherVariable	1

round

Rounds numbers. Supported for extended event schema fields of the integer and float types.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomFloatingPoint1=7.75; DeviceCustomFloatingPoint2=7.5 otherVariable=7.2)	Usage result
  round(DeviceCustomFloatingPoint1)	8
  round(DeviceCustomFloatingPoint2)	8
  round($otherVariable)	7

ceil

Rounds up numbers. Supported for extended event schema fields of the integer and float types.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomFloatingPoint1=7.15; otherVariable=8.2)	Usage result
  ceil(DeviceCustomFloatingPoint1)	8
  ceil($otherVariable)	9

floor

Rounds down numbers. Supported for extended event schema fields of the integer and float types.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomFloatingPoint1=7.15; otherVariable=8.2)	Usage result
  floor(DeviceCustomFloatingPoint1)	7
  floor($otherVariable)	8

abs

Gets the modulus of a number. Supported for extended event schema fields of the integer and float types.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomNumber1=-7; otherVariable=-2)	Usage result
  abs(DeviceCustomFloatingPoint1)	7
  abs($otherVariable)	2

pow

Exponentiates a number. Supported for extended event schema fields of the integer and float types.

The parameters must be specified in the following sequence:

1. Base — real numbers.
2. Exponent — natural numbers or real numbers.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples

  pow(DeviceCustomNumber1, DeviceCustomNumber2)

  pow($otherVariable, DeviceCustomNumber1)

str_join

Join multiple strings into one using a separator. Supported for extended event schema fields of the integer and float types.

The parameters must be specified in the following sequence:

1. Separator. String.
2. String 1, string 2, string N. At least 2 expressions.

   Usage examples	Usage result
   str_join('|', to_lower(Name), to_upper(Name), Name)	String.

conditional

Get one value if a condition is met and another value if the condition is not met. Supported for extended event schema fields of the integer and float types.

The parameters must be specified in the following sequence:

1. Condition. String. The syntax is similar to the conditions of the Where statement in SQL. You can use the functions of the KUMA variables and references to other variables in a condition.
2. The value if the condition is met. Expression.
3. The value if the condition is not met. Expression.

Supported operators:

• AND
• OR
• NOT
• =
• !=
• <
• <=
• >
• >=
• LIKE (passes a RE2 regular expression, not an SQL expression)
• ILIKE (passes a RE2 regular expression, not an SQL expression)
• BETWEEN
• IN
• IS NULL (check for an empty value, such as 0 or an empty string)

  Usage examples (the value depends on arguments 2 and 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')

Operations for extended event schema fields

For extended event schema fields of the string type, the following operations are supported:

• len
• to_lower
• to_upper
• append
• prepend
• substring
• tr
• replace
• regexp_replace
• regexp_capture

For extended event schema fields of the integer or float type, the following operations are supported:

• Basic mathematical operations:
• round
• ceil
• floor
• abs
• pow
• str_join
• conditional

For extended event schema fields of the array of integers, array of floats, and array of strings types, KUMA supports the following functions:

• Get the i-th element of the array. Example: item(<type>.someStringArray).
• Get an array of values. Example: <type>.someStringArray. Returns ["string1", "string2", "string3"].
• Get the count of elements in an array. Example: len(<type>.someStringArray). Returns ["string1", "string2"].
• Gett unique elements from an array. Example: distinct_items(<type>.someStringArray).
• Generate a TSV string of array elements. Example: to_string(<type>.someStringArray).
• Sort the elements of the array. Example: sort_items(<type>.someStringArray).

  In the examples, instead of <type>, you must specify the array type: NA for an array of integers, FA for an array of floats, SA for an array of strings.

For fields of the array of integers and array of floats types, the following functions are supported:

• math_min returns the minimum element of an array. Example: math_min(NA.NumberArray), math_min(FA.FloatArray).
• math_max returns the maximum element of an array Example: math_max(NA.NumberArray), math_max(FA.FloatArray).
• math_avg returns the average value of an array. Example: math_avg(NA.NumberArray), math_avg(FA.FloatArray).

Page top