Predefined EQL Functions

A list of functions that are available in the EQL.

The conversion functions are typically used when adding a new data model, or when you need to define new columns, where the expressions for new columns can use conversion functions to convert between data types and combine them using various operators. For instructions on how to add a new data model, see Creating a Data Model in Graphical Mode.

Conversion functions

Conversion functions
Function Name Arguments Returns
ToTimestamp
  • (expression, formatString)
  • (expression, formatString, timezone)
  • (expression, formatString, timezone, defaultValue)
The expression, which should evaluate to a string, is interpreted as a time according to the supplied formatString. If the conversion fails, null is returned, unless a default string is provided, which is interpreted as a time and returned.

Example: ToTimestamp( logFileStringTimestampField, "dd, MM, yyyy HH:mm:ss", "America/ Los_Angeles", "01, 01, 1970 00:00:00")

Note: If timezone is omitted or is empty, the system default timezone is used.

If formatString does not contain a year, then when the function is being evaluated in the context of processing an event, the year from the event time (sys_eventTime) is used. If this results in a timestamp that is later than the event time, the prior year is used.

ToIP
  • (expression)
  • (expression, defaultValue)
Converts the expression to an IP address (Java InetAddress). If the conversion fails, returns null; but if a default string is provided, it is interpreted as an IP address and returned.

Example: ToIP(ipAddressField, "10.0.0.1")
ToTimestampString
  • (expression, formatString)
  • (expression, formatString, timezone)
  • (expression, formatString, timezone, defaultValue)
Same as ToTimestamp, except that the expression is converted to string to get a printable timestamp.

Example: ToTimestampString(timestamp , "dd, MM, yyyy HH:mm:ss", "America/Los_Angeles", "01, 01, 1970 00:00:00")

Note: If timezone is omitted or is empty, the system default timezone is used.

ToInt
  • (expression)
  • (expression, defaultValue)
Returns the integer value of the expression; or the default value if not convertible.

Example: ToInt("1348") or ToInt(numberField, 0)
ToLong
  • (expression)
  • (expression, defaultValue)
The obvious conversion to Long with default value taken if not convertible.

Example: ToLong("1348") or ToLong(numberField, 0)
ToString
  • (expression)
  • (expression, defaultValue)
Returns the string string value of the expression; or the default value if not convertible.

Example: ToString(124.5) or ToString(numberField, "null")
ToFloat
  • (expression)
  • (expression, defaultValue)
Returns the Float value of the expression; or the default value if not convertible.

Example: ToFloat("1348.2") or ToLong(numberField, 0.0)

Note: LogLogic LMI uses double precision (that is 64 bits) when storing floating point numbers.

ToBool
  • (expression)
  • (expression, defaultValue)
Returns the Boolean value of the expression; or the default value if not convertible.

Example: ToBool("FALSE") or ToBool(col1, FALSE)
ExtractJson
  • (expression, extraction path)
  • (expression, extraction path, default value)
The expression, which is a JSON string is parsed. A field is extracted from the expression using the extraction path. If either the expression or the path are invalid, an optional default value is returned.

Example: ExtractJson("{"cat": {"color":" blue"}}", "cat.color", "burlesque") returns a string "blue" which is a JSON value of color, which is a JSON value of cat.

ExtractKvp
  • (expression, extraction path)
  • (expression, extraction path, nested KVP delimiters /default "{}"/)
  • (expression, extraction path, nested KVP, deliiter / default ","/)
  • (expression, extraction path, nested KVP, delimiter, separator /default "="/)
  • (expression, extraction path, nested KVP, delimiter, separator, escape character / default "\\"/)
  • (expression, extraction path, nested KVP, delimiter, separator, escape character, default value)
The expression, which is a nested KVP string is parsed. A field is extracted from the expression using the extraction path. If either the expression or the path are invalid, an optional default value is returned.

Example: ExtractKvp(" alert={ agent={ hostname=esbqa01, dns=none}}" , "alert.agent.dns") returns a string "none".

or

ExtractKvp("(abc^def|asd^aaa)" , "asd", "()", "|", "^") returns "aaa".

String Functions

The smart list functions are usually used in filter expressions and data model.

Function Name Arguments Returns
lookup (string 1, string 2, [string 3]) Returns the value associated with string2 in the Enrichment list named string1.

Examples: 

lookup("list1", "key1")
lookup ("list1", "key1", "default_return_value"
$list1("key1")
$list1("key1", "default_return_value")
length (expression) Returns the length of the string value of the evaluated expression. For example, if an expression is an integer, it is converted to a string first.

Example: length("abc") is 3, length(3145) is 4 (after converting the integer 3145 to the string "3145")

Transform​String
  • (stringToTransform, regularExpression, template)
  • (stringToTransform, regularExpression, template, defaultValue)
The function tries to match the stringToTransform string with the regular expression, and then returns the template with references to groups in the regular expression substituted with the actual values. To refer to groups, use $1, $2, so on, to refer to numbered groups, and $<name> to refer to named groups. If the string does not match, or is there any other error, the default value is returned (or NULL if not specified).

Example:

TransformString("myName=loglogic" , "myName=(\\S*)", "the name is $1")

returns: "the name is loglogic".

lower (string) Returns the lower case of the string
upper (string) Returns the upper case of the string
trim (string) Returns the trimmed string (without leading and trailing spaces).
substitute (string1, string2, string3) Substitutes string2 by string3 in string1.
left (string, Int) <int> Returns the left characters of string.
right (string, Int) <int> Returns the right characters of string.
  • mid
  • substr
  • substring
(string, Int 1, Int 2) Returns the characters from string starting at offset int1 for a length of int2.
position (string 1, string 2) Returns the index of the first occurrence of string2 within string1; -1 if no occurrence is found.
concatenate (string 1, string 2, …) Returns the concatenation of all strings passed as arguments.
find (string1, string2, index ) Returns the position (from the beginning of string1) of the first occurrence of string2 within string1; and -1 if no occurrence is found.

Searching starts beyond the position specified by index.

Example:

find("Here Here", "e", 3 )

returns 6

findlast (string1, string2, index ) Returns the position (from the beginning of string1) of the last occurrence of string2 within string1; and -1 if no occurrence is found.

Searching starts beyond the position specified by index.

Example:

findlast("Here Here", "e" )

returns 8

findnth (string1, string2, n, index ) Returns the position (from the beginning of string1) of the 'n'th occurrence of string2 within string1; and -1 if no occurrence is found.

Searching starts beyond the position specified by index.

Example:

findnth("Here Here", "r", 3, 2 )

returns -1

  • substituteall
  • substitutefirst
(source, regex_pattern, replacement_string)
  • Returns the new string after replacing the pattern in the source string with the replacement string.
  • Returns the original string if the pattern is invalid or not found.

    Examples:

    • substituteall('(4)john(3)hot(6)doggie(3)com', '(\d+)', '!' )

      returns '!john!hot!doggie!com'

    • substitutefirst( '(4)john(3)hot(6)doggie(3)com', '(\d+)', '!' )

      returns '!john(3)hot(6)doggie(3)com'
split (input_string, 'separator', position_num)

Returns the string at the specified position, extracted from the original string specified in input_string; and an empty string if no occurrence is found.

  • separator can be any regex pattern
  • position_num starts at 0
  • The function can be used within EQL, SQL, and ECL queries for advanced search queries, aggregation rule queries, correlation Blok definitions, and column parsing rules of a data model. However, the function cannot be used in a GROUP BY clause of aggregation rules.

For examples of these functions in SQL and EQL queries, see Search Examples.

Comparison Functions

Function Name Arguments Returns
NaturalEqualTo (arg1, arg2)
  • True if arg1 equals arg2
  • False if arg1 is not equal to arg2
  • False if only one of the arguments is NULL
  • True if both arguments are NULL
NaturalNotEqualTo (arg1, arg2)
  • True if arg1 is not equal to arg2
  • False if arg1 equals arg2
  • True if only one of the arguments is NULL
  • False if both arguments are NULL

Math Functions

Function Name Arguments Returns
Power base, exponent Returns the value of base raised to the power of exponent. Any null argument returns null.
Round
  • (numeric)
  • (numeric, [integer])
Returns a FLOAT value of the numeric argument rounded to the number of decimal places specified by integer. The argument integer is optional, and the default value is zero if not provided.

The numeric value is rounded mid-way and away from zero. A null argument returns null. If the second argument is positive, it represents the number of decimal places to the right of the decimal point, whereas if it is negative, it represents the number of places to the left of the decimal point which become a zero.

For example:

FunctionReturns
ROUND( 12.345 )12.0
ROUND( 12.345, 2 ) 12.35
ROUND( 123.45, -1 )120.0
ROUND( 34567, -2 ) 34600
ROUND( -3456.5 ) -3457.0
Sqrt numeric Returns the square root of the argument or null if the argument is null.
sum
  • (<columnName>)
  • (distinct <columnName>)
Returns the sum of all values in the column specified by <columnName>. If distinct is specified, returns the sum of the distinct values in the column.

For example, if the column 'contentLength' contains the values 2,3,4,5,5,6:

FunctionReturns
sum (contentLength)25
sum (distinct contentLength) 20

Conditional Functions

Function Name Arguments Returns
IIF Condition, then, else Returns the value of the 'then' clause if the condition is true, otherwise the value of the 'else' clause.

Example: IIF(true, “a”, “b”) returns “a” if true and “b” if false

Time functions

The following time functions are available:
  • seconds (timestamp, [multiplier])
  • minutes (timestamp, [multiplier])
  • hours (timestamp, [multiplier])
  • days (timestamp, [multiplier])
  • weeks (timestamp, [multiplier])
  • months (timestamp, [multiplier])
  • years (timestamp, [multiplier])

Each function returns the value of the specified timestamp parameter truncated to the corresponding time unit (seconds, minutes, hours, and so on).

If the optional parameter multiplier is specified, then the function creates a time bucket of the specified units and with the precision of the multiplier, and returns the truncated timestamp at the start of the time interval specified by multiplier.

Example
Consider the following example: 
seconds(sys_eventTime, 10)

This function creates a time bucket of 10 seconds, and returns the truncated timestamp out of the specified sys_eventTime at the start of the 10-second interval. That is, if the value of sys_eventTime is "2020-06-26 10:57:24", then it truncates the value to "2020-06-26 10:57:20".

Miscellaneous Functions

Function Name Arguments Returns
geoiplookup

By using this function within SQL and EQL queries, you can search logs that originated from a particular geographical area such as location, country, city, postal code, and so on. You can use the function in Advanced Search and Advanced Dashboards.

  • (IPaddress)
  • (IPaddress, field_option)

In the IPaddress parameter, you can specify an IP address or a column that stores an IP address such as Inet_Address.

The field_option parameter can be one of the following values:

  • location
  • continent
  • country
  • city
  • postal
  • subdivision
  • domain
  • connectiontype
  • asn

Returns the geographical information of a specified IPv4 or IPv6 address. Returns the country name if the field_option parameter is not specified.
Note: To use this function, the MaxMind database must be available on your appliance. If any errors are displayed, contact your administrator.
matchcidr

You can use the function within SQL, EQL, and ECL queries, and in turn, in other functionality that make use of these queries.

  • (IP_string_format, IP_address_to_Match)
  • (IP_string_format, IP_address_to_Match, key)
  • ( CIDR_expression, extractIP(input_column_name or custom_input_value) )

In the IP_string_format parameter, you can specify a CIDR address, single IPv4 or IPv6 address, a comma-separated list of CIDR IP addresses or a range, a hyphen-separated range of IP addresses, or an enrichment list.

In the IP_address_to_Match parameter, specify the column name from the logs, which are to be matched against the IP_string_format parameter. The data type of the column must be INET_ADDR.

The key parameter specifies a key name in the enrichment list. The key parameter is mandatory when using this function in correlation Bloks. You must provide either a key name or an empty string ("").

  • Returns those IP addresses from the IP_address_to_Match parameter, which belong to the IP addresses specified in the IP_string_format list.
  • If you use extractIPs within matchcidr, then extractIPs extracts all IP addresses from either a column containing a list of IP addresses or a list of IP addresses. If any of the IP addresses matches with the CIDR_expression, then matchcidr returns true; otherwise false.
extractIPs

You can use the function within SQL, EQL, and ECL queries, and in turn, in the matchcidr function.

  • for extractIPs: (list_of_IP_addresses)
  • within matchcidr: (input_column) or (custom_input_value)

The input list of IP addresses can contain IPv4, IPv6, or IPv6 compressed addresses.

Returns a list of IP addresses as a comma-separated string; or an empty string if no IP addresses are found within the input string.

For examples of geoiplookup and matchcidr functions in SQL and EQL queries, see Search Examples.