Predefined EQL Functions

A list of functions that are available in the EQL.

Conversion functions. 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 Adding a Data Model in Graphical Mode.
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)
Convert the expression to an IP address (Java InetAddress). If the conversion fails, null is returned, unless a default string is provided, which 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 it gets 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)
The obvious conversion to integer with default value taken 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)
The obvious conversion to string with default value taken if not convertible.

Example: ToString(124.5) or ToString(numberField, "null")

ToFloat
  • (expression)
  • (expression, defaultValue)
The obvious conversion to Float with default value taken 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)
The obvious conversion to Boolean with default value taken 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]) 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)
It tries to match the stringToTransform 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) Lower case of the string
upper (string) Upper case of the string
trim (string) Trimmed string (without leading and trailing spaces).
substitute (string 1, string 2, string 3) Substitute string 2 by string 3 in string 1.
left (string, Int) <int> left characters of string
right (string, Int) <int> right characters of string
  • mid
  • substr
  • substring
(string, Int 1, Int 2) Characters from string starting at offset <int1> for a length of <int2>.
position (string 1, string 2) Index of the first occurrence of string2 within string1; -1 if no occurrence is found.
concatenate (string 1, string 2, …) Concatenation of all strings passed as arguments.
find (string1, string2, index ) 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 ) 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 ) 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'

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:
Function Returns
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:
Function Returns
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)

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 a either 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.
For examples of geoiplookup and matchcidr functions in SQL and EQL queries, see Search Examples.