Functions appear in expressions and take positional
and/or named arguments, producing a value as a result of their computation.
Function signatures have the following notation:
f (arg1 :< type > , arg2 =< type > , [arg3 = type]) -> < type >
arg:<type>
: positional argument
arg=<type>
: named argument
[arg=type]
: optional (named) argument
-> <type>
: function return type
TQL features the uniform function call syntax
(UFCS) , which
allows you to interchangeably call a function with at least one argument either
as free function or method . For example, length(str)
and str.length()
resolve to the identical function call. The latter syntax is particularly
suitable for function chaining, e.g., x.f().g().h()
reads left-to-right as
“start with x
, apply f()
, then g()
and then h()
,” compared to
h(g(f(x)))
, which reads “inside out.”
Throughout our documentation, we use the free function style in the synopsis
but often resort to the method style when it is more idiomatic.
Computes the conjunction (AND) of all grouped boolean values.
Computes the disjunction (OR) of all grouped boolean values.
Creates a list of all non-null grouped values, preserving duplicates.
Counts the events or non-null grouped values.
Counts all distinct non-null grouped values.
count_distinct ([ 1 , 2 , 2 , 3 ])
Counts the events or non-null grouped values matching a given predicate.
count_if ([ 1 , 2 , null ], x => x > 1 )
Creates a sorted list without duplicates of non-null grouped values.
Computes the Shannon entropy of all grouped values.
Takes the first non-null grouped value.
Takes the last non-null grouped value.
Computes the maximum of all grouped values.
Computes the mean of all grouped values.
Computes the approximate median of all grouped values using a t-digest algorithm.
Computes the minimum of all grouped values.
Takes the most common non-null grouped value.
Returns a fallback
value if primary
is null
.
Computes the specified quantile of all grouped values.
quantile ([ 1 , 2 , 3 , 4 ], q = 0.5 )
Computes the standard deviation of all grouped values.
Computes the sum of all values.
Returns a list of all grouped values alongside their frequency.
Computes the variance of all grouped values.
Computes the bit-wise AND of its arguments.
Computes the bit-wise NOT of its argument.
Computes the bit-wise OR of its arguments.
Computes the bit-wise XOR of its arguments.
Performs a bit-wise left shift.
Performs a bit-wise right shift.
Decodes bytes as Base64.
decode_base64 ( "VGVuemly" )
Decodes bytes from their hexadecimal representation.
Decodes URL encoded strings.
decode_url ( "Hello%20World" )
Encodes bytes into their hexadecimal representation.
Encodes strings using URL encoding.
encode_url ( "Hello World" )
Computes an MD5 hash digest.
Computes a SHA-1 hash digest.
Computes a SHA-224 hash digest.
Computes a SHA-256 hash digest.
Computes a SHA-384 hash digest.
Computes a SHA-512 hash digest.
Computes an XXH3 hash digest.
Checks whether an IP address has version number 4.
Checks whether an IP address has version number 6.
Retrieves the network address of a subnet.
Inserts an element at the back of a list.
Gets a field from a record or an element from a list
Retrieves the length of a list.
Maps each list element to an expression.
Inserts an element at the start of a list.
Sorts lists and record fields.
Filters list elements based on a predicate.
Combines two lists into a list of pairs.
Returns the absolute value.
Computes the ceiling of a number or a time/duration with a specified unit.
Computes the floor of a number or a time/duration with a specified unit.
Generates a random number in [0,1] .
Rounds a number or a time/duration with a specified unit.
Computes the square root of a number.
Computes the Community ID for a network connection/flow.
community_id (src_ip = 1.2.3.4 , dst_ip = 4.5.6.7 , proto = "tcp" )
Decapsulates packet data at link, network, and transport layer.
Encrypts an IP address via Crypto-PAn.
encrypt_cryptopan ( 1.2.3.4 )
Returns the category_name
for a given category_uid
.
Returns the category_uid
for a given category_name
.
ocsf :: category_uid ( "Findings" )
Returns the class_name
for a given class_uid
.
Returns the class_uid
for a given class_name
.
ocsf :: class_uid ( "DNS Activity" )
Returns the type_name
for a given type_uid
.
Returns the type_uid
for a given type_name
.
ocsf :: type_uid ( "SSH Activity: Fail" )
Parses a string as a CEF message
Parses a string as CSV (Comma-Separated Values).
string . parse_csv (header = [ "a" , "b" ])
Parses a string according to a grok pattern.
string . parse_grok ( "%{IP:client} …" )
Parses a string as a JSON value.
Parses a string as key-value pairs.
Parses a string as a LEEF message
Parses a string as space separated values.
string . parse_ssv (header = [ "a" , "b" ])
Parses a string as a Syslog message.
Parses a string as tab separated values.
string . parse_tsv (header = [ "a" , "b" ])
Parses a string as delimiter separated values.
string . parse_xsv ( "," , ";" , "" , header = [ "a" , "b" ])
Parses a string as a YAML value.
Prints records as Common Event Format (CEF) messages
extension . print_cef (cef_version = "0" , device_vendor = "Tenzir" , device_product = "Tenzir Node" , device_version = "5.5.0" , signature_id = id, name = "description" , severity = "7" )
Prints a record as a comma-separated string of values.
Transforms a value into a JSON string.
Prints records in a key-value format.
Prints records as LEEF messages
attributes . print_leef (vendor = "Tenzir" ,product_name = "Tenzir Node" , product_name = "5.5.0" ,event_class_id = id)
Transforms a value into a single-line JSON string.
Prints a record as a space-separated string of values.
Prints a record as a tab-separated string of values.
Prints a record as a delimited sequence of values.
Prints a value as a YAML document.
Gets a field from a record or an element from a list
Checks whether a record has a specified field.
Retrieves a list of field names from a record.
Combines two records into a single record by merging their fields.
Sorts lists and record fields.
Reads Tenzir's configuration file.
Reads an environment variable.
Reads a secret from a store.
Retrieves the network address of a subnet.
Counts the number of days
in a duration.
Counts the number of hours
in a duration.
Counts the number of microseconds
in a duration.
Counts the number of milliseconds
in a duration.
Counts the number of minutes
in a duration.
Counts the number of months
in a duration.
Counts the number of nanoseconds
in a duration.
Counts the number of seconds
in a duration.
Counts the number of weeks
in a duration.
Counts the number of years
in a duration.
Extracts the day component from a timestamp.
Converts a number to equivalent days.
Formats a time into a string that follows a specific format.
ts . format_time ( "%d/ %m/%Y" )
Interprets a duration as Unix time.
from_epoch (time_ms * 1ms )
Extracts the hour component from a timestamp.
Converts a number to equivalent hours.
Converts a number to equivalent microseconds.
Converts a number to equivalent milliseconds.
Extracts the minute component from a timestamp.
Converts a number to equivalent minutes.
Extracts the month component from a timestamp.
Converts a number to equivalent months.
Converts a number to equivalent nanoseconds.
Gets the current wallclock time.
Parses a time from a string that follows a specific format.
"10/11/2012" . parse_time ( "%d/%m/%Y" )
Extracts the second component from a timestamp with subsecond precision.
Converts a number to equivalent seconds.
Interprets a time value as duration since the Unix epoch.
Converts a number to equivalent weeks.
Extracts the year component from a timestamp.
Converts a number to equivalent years.
Reads a file's contents.
file_contents ( "/path/to/file" )
Extracts the file name from a file path.
file_name ( "/path/to/log.json" )
Extracts the parent directory from a file path.
parent_dir ( "/path/to/log.json" )
Checks if a string ends with a specified substring.
Checks if a string is alphanumeric.
Checks if a string contains only alphabetic characters.
Checks if a string is in lowercase.
Checks if a string contains only numeric characters.
Checks if a string contains only printable characters.
Checks if a string follows title case.
Checks if a string is in uppercase.
Returns the length of a string in bytes.
Returns the length of a string in characters.
Checks if a string partially matches a regular expression.
"Hi" . match_regex ( "[Hh]i" )
Slices a string with offsets and strides.
"Hi" . slice (begin = 2 , stride = 4 )
Checks if a string starts with a specified substring.
"hello" . starts_with ( "he" )
Capitalizes the first character of a string.
Joins a list of strings into a single string using a separator.
join ([ "a" , "b" , "c" ], "," )
Replaces characters within a string.
"hello" . replace ( "o" , "a" )
Replaces characters within a string based on a regular expression.
"hello" . replace ( "l+o" , "y" )
Reverses the characters of a string.
Splits a string into substrings.
Splits a string into substrings with a regex.
split_regex ( "a1b2c" , r"\d" )
Converts a string to lowercase.
Converts a string to title case.
Converts a string to uppercase.
Trims whitespace from both ends of a string.
Trims whitespace from the end of a string.
Trims whitespace from the start of a string.
Casts an expression to a duration value.
Casts an expression to a float.
Casts an expression to an integer.
Casts an expression to an IP address.
Casts an expression to a string.
Casts an expression to a subnet value.
Casts an expression to a time value.
Casts an expression to an unsigned integer.
Retrieves the type id of an expression.
Retrieves the type definition of an expression.