Skip to content

Functions

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.
all([true,true,false])
Computes the disjunction (OR) of all grouped boolean values.
any([true,false,true])
Creates a list of all non-null grouped values, preserving duplicates.
collect([1,2,2,3])
Counts the events or non-null grouped values.
count([1,2,null])
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.
distinct([1,2,2,3])
Computes the Shannon entropy of all grouped values.
entropy([1,1,2,3])
Takes the first non-null grouped value.
first([null,2,3])
Takes the last non-null grouped value.
last([1,2,null])
Computes the maximum of all grouped values.
max([1,2,3])
Computes the mean of all grouped values.
mean([1,2,3])
Computes the approximate median of all grouped values using a t-digest algorithm.
median([1,2,3,4])
Computes the minimum of all grouped values.
min([1,2,3])
Takes the most common non-null grouped value.
mode([1,1,2,3])
Returns a fallback value if primary is null.
x.otherwise(0)
Computes the specified quantile of all grouped values.
quantile([1,2,3,4], q=0.5)
Computes the standard deviation of all grouped values.
stddev([1,2,3])
Computes the sum of all values.
sum([1,2,3])
Returns a list of all grouped values alongside their frequency.
value_counts([1,2,2,3])
Computes the variance of all grouped values.
variance([1,2,3])
Computes the bit-wise AND of its arguments.
bit_and(lhs, rhs)
Computes the bit-wise NOT of its argument.
bit_not(x)
Computes the bit-wise OR of its arguments.
bit_or(lhs, rhs)
Computes the bit-wise XOR of its arguments.
bit_xor(lhs, rhs)
Performs a bit-wise left shift.
shift_left(lhs, rhs)
Performs a bit-wise right shift.
shift_right(lhs, rhs)
Decodes bytes as Base64.
decode_base64("VGVuemly")
Decodes bytes from their hexadecimal representation.
decode_hex("4e6f6E6365")
Decodes URL encoded strings.
decode_url("Hello%20World")
Encodes bytes as Base64.
encode_base64("Tenzir")
Encodes bytes into their hexadecimal representation.
encode_hex("Tenzir")
Encodes strings using URL encoding.
encode_url("Hello World")
Computes an MD5 hash digest.
hash_md5("foo")
Computes a SHA-1 hash digest.
hash_sha1("foo")
Computes a SHA-224 hash digest.
hash_sha224("foo")
Computes a SHA-256 hash digest.
hash_sha256("foo")
Computes a SHA-384 hash digest.
hash_sha384("foo")
Computes a SHA-512 hash digest.
hash_sha512("foo")
Computes an XXH3 hash digest.
hash_xxh3("foo")
Checks whether an IP address has version number 4.
is_v4(1.2.3.4)
Checks whether an IP address has version number 6.
is_v6(::1)
Retrieves the network address of a subnet.
10.0.0.0/8.network()
Inserts an element at the back of a list.
xs.append(y)
Merges two lists.
concatenate(xs, ys)
Gets a field from a record or an element from a list
list.get(index, default)
Retrieves the length of a list.
[1,2,3].length()
Maps each list element to an expression.
xs.map(x => x + 3)
Inserts an element at the start of a list.
xs.prepend(y)
Sorts lists and record fields.
xs.sort()
Filters list elements based on a predicate.
xs.where(x, x > 5)
Combines two lists into a list of pairs.
zip(xs, ys)
Returns the absolute value.
abs(-42)
Computes the ceiling of a number or a time/duration with a specified unit.
ceil(4.2)
Computes the floor of a number or a time/duration with a specified unit.
floor(4.8)
Generates a random number in [0,1].
random()
Rounds a number or a time/duration with a specified unit.
round(4.6)
Computes the square root of a number.
sqrt(49)
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.
decapsulate(this)
Encrypts an IP address via Crypto-PAn.
encrypt_cryptopan(1.2.3.4)
Returns the category_name for a given category_uid.
ocsf::category_name(2)
Returns the category_uid for a given category_name.
ocsf::category_uid("Findings")
Returns the class_name for a given class_uid.
ocsf::class_name(4003)
Returns the class_uid for a given class_name.
ocsf::class_uid("DNS Activity")
Returns the type_name for a given type_uid.
ocsf::type_name(400704)
Returns the type_uid for a given type_name.
ocsf::type_uid("SSH Activity: Fail")
Parses a string as a CEF message
string.parse_cef()
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.
string.parse_json()
Parses a string as key-value pairs.
string.parse_kv()
Parses a string as a LEEF message
string.parse_leef()
Parses a string as space separated values.
string.parse_ssv(header=["a","b"])
Parses a string as a Syslog message.
string.parse_syslog()
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.
string.parse_yaml()
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.
record.print_csv()
Transforms a value into a JSON string.
record.print_json()
Prints records in a key-value format.
record.print_kv()
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.
record.print_ndjson()
Prints a record as a space-separated string of values.
record.print_ssv()
Prints a record as a tab-separated string of values.
record.print_tsv()
Prints a record as a delimited sequence of values.
record.print_tsv()
Prints a value as a YAML document.
record.print_yaml()
Gets a field from a record or an element from a list
list.get(index, default)
Checks whether a record has a specified field.
record.has("field")
Retrieves a list of field names from a record.
record.keys()
Combines two records into a single record by merging their fields.
merge(foo, bar)
Sorts lists and record fields.
xs.sort()
Reads Tenzir's configuration file.
config()
Reads an environment variable.
env("PATH")
Reads a secret from a store.
secret("KEY")
Retrieves the network address of a subnet.
10.0.0.0/8.network()
Counts the number of days in a duration.
count_days(100d)
Counts the number of hours in a duration.
count_hours(100d)
Counts the number of microseconds in a duration.
count_microseconds(100d)
Counts the number of milliseconds in a duration.
count_milliseconds(100d)
Counts the number of minutes in a duration.
count_minutes(100d)
Counts the number of months in a duration.
count_months(100d)
Counts the number of nanoseconds in a duration.
count_nanoseconds(100d)
Counts the number of seconds in a duration.
count_seconds(100d)
Counts the number of weeks in a duration.
count_weeks(100d)
Counts the number of years in a duration.
count_years(100d)
Extracts the day component from a timestamp.
ts.day()
Converts a number to equivalent days.
days(100)
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.
ts.hour()
Converts a number to equivalent hours.
hours(100)
Converts a number to equivalent microseconds.
microseconds(100)
Converts a number to equivalent milliseconds.
milliseconds(100)
Extracts the minute component from a timestamp.
ts.minute()
Converts a number to equivalent minutes.
minutes(100)
Extracts the month component from a timestamp.
ts.month()
Converts a number to equivalent months.
months(100)
Converts a number to equivalent nanoseconds.
nanoseconds(100)
Gets the current wallclock time.
now()
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.
ts.second()
Converts a number to equivalent seconds.
seconds(100)
Interprets a time value as duration since the Unix epoch.
since_epoch(2021-02-24)
Converts a number to equivalent weeks.
weeks(100)
Extracts the year component from a timestamp.
ts.year()
Converts a number to equivalent years.
years(100)
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.
"hello".ends_with("lo")
Checks if a string is alphanumeric.
"hello123".is_alnum()
Checks if a string contains only alphabetic characters.
"hello".is_alpha()
Checks if a string is in lowercase.
"hello".is_lower()
Checks if a string contains only numeric characters.
"1234".is_numeric()
Checks if a string contains only printable characters.
"hello".is_printable()
Checks if a string follows title case.
"Hello World".is_title()
Checks if a string is in uppercase.
"HELLO".is_upper()
Returns the length of a string in bytes.
"hello".length_bytes()
Returns the length of a string in characters.
"hello".length_chars()
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.
"hello".capitalize()
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.
"hello".reverse()
Splits a string into substrings.
split("a,b,c", ",")
Splits a string into substrings with a regex.
split_regex("a1b2c", r"\d")
Converts a string to lowercase.
"HELLO".to_lower()
Converts a string to title case.
"hello world".to_title()
Converts a string to uppercase.
"hello".to_upper()
Trims whitespace from both ends of a string.
" hello ".trim()
Trims whitespace from the end of a string.
"hello ".trim_end()
Trims whitespace from the start of a string.
" hello".trim_start()
Casts an expression to a duration value.
duration("1.34w")
Casts an expression to a float.
float(42)
Casts an expression to an integer.
int(-4.2)
Casts an expression to an IP address.
ip("1.2.3.4")
Casts an expression to a string.
string(1.2.3.4)
Casts an expression to a subnet value.
subnet("1.2.3.4/16")
Casts an expression to a time value.
time("2020-03-15")
Casts an expression to an unsigned integer.
uint(4.2)
Retrieves the type id of an expression.
type_id(1 + 3.2)
Retrieves the type definition of an expression.
type_of(this)
Flattens nested data.
flatten(this)
Unflattens nested data.
unflatten(this)

Last updated: