Functions

DSL functions, both built-in and user-defined (UDFs), are used by the expression language for data processing operations such as building features, datasets, and metrics.

Sections

Built-ins
UDFs

Built-ins 

These functions are built-in.

ABS(d)

Return the absolute value of (d) as a double.

Parameters: d – (Double) A number.
Return type: Double

Examples

ABS(-1)

1.0

ACOS(a)

Returns the arc cosine of a number.

Parameters: a – (Double) A number between -1 and 1
Return type: Double

Examples

ACOS(COS(PI()))

3.141592653589793

AG_MAX(a, b[, ...n])

Return the maximum value of {a}, {b}, {…n} ignoring nulls.

Parameters

a – (Number) A number.
b – (Number) A number.
...n – (Number) Any number of additional comma-separated parameters of the appropriate type.

Return type

Number

Examples

AG_MAX([3,2,1,11,-1,-20])

11

AG_MIN(a, b[, ...n])

Return the minimum value from {a}, {b}, {…n} ignoring nulls.

Parameters

a – (Number) A number.
b – (Number) A number.
...n – (Number) Any number of additional comma-separated parameters of the appropriate type.

Return type

Number

Examples

AG_MIN([3,2,1,11,-1,-20])

-20

ALL_EVENTS(type)

return all events on the timeline from the given TimeSeries.

Parameters: type – (String) (optional) the type of the TimeSeries to return
Return type: List

AND(a, AND, b)

Logically AND {a} with {b}.

Parameters

a – (Double) A number.
AND – (BoolAndFunction) The operator itself.
b – (Double) A number.

Return type

Boolean

ASIN(a)

Returns the arc sine of a number.

Parameters: a – (Double) A number between -1 and 1
Return type: Double

Examples

ASIN(SIN(PI()/2))

1.5707963267948966

ATAN(a)

Returns the arc tangent of a number.

Parameters: a – (Double) A number between -1 and 1
Return type: Double

Examples

ATAN(TAN(PI()*(-1/4)))

-0.7853981633974483

AVG(values)

Return the average (mean) of a list of numeric elements. If a single numeric element is passed, it is returned back. If a non-numeric element or null value is processed, null is returned.

Parameters: values – (Object) A list of values to average
Return type: Double

Examples

AVG([3,2,1,11,-1,-20])

-0.6666666666666666

BUCKET(value, start, stop, step)

Converts the input into the nearest value between {start} and {stop} that is some whole number of {step}s greater than {start}. Used for taking a continuous value and converting it to a discrete value within a pair of bounds.

Parameters

value – (Double) The number value to bucket
start – (Double) The lower bound of the bucket
stop – (Double) The upper bound of the bucket
step – (Double) The step interval of the bucket

Return type

Double

CAUSAL_EFFECT(model_identifier, metrics_type, residual_timestamp)

Computes causal effect scores by using several variants of a lift model.

Parameters

model_identifier – (Object) The identifier (model type or id) to resolve the model with
metrics_type – (String) The type of metric to compute (EXPECTED, REALIZED, or RESIDUAL for treatment-level metrics or CONV_RATE or INCR_RATE for time-rates of outcome-level metrics)
residual_timestamp – (Long) A milliseconds timestamp to use to score residual incrementality

Return type

Double

CAUSAL_EFFECT_ENSEMBLE(model_identifier, metrics_type, residual_timestamp)

Computes causal effect scores by using several variants of a lift model.

Parameters

model_identifier – (Object) The identifier (model type or id) to resolve the model with
metrics_type – (String) The type of metric to compute (EXPECTED, REALIZED, or RESIDUAL for treatment-level metrics or CONV_RATE or INCR_RATE for time-rates of outcome-level metrics)
residual_timestamp – (Long) A milliseconds timestamp to use to score residual incrementality

Return type

List

CBRT(d)

Returns the positive cube root of {d}.

Parameters: d – (Double) A number.
Return type: Double

CDF(distName, x_value, scale)

returns the cumulative distribution function (CDF) of the given x_value and scale parameters, using the provided distribution.

Supported distributions:

positive-support distributions (short-form abbreviations): exponential (e, exp), uniform (u, unif), triangular (t, tri), half-normal (h, hnorm), and half-logistic (l, hlog).

positive- & negative-support distributions are the symmetric analogs of the positive-support distributions: laplace (a, lap), rectangular (r, rect), symmetric triangular (s, stri), normal (n, norm), and logistic (o, log).

time-independent “constant” distribution (c, const) is also useful for various use cases.

Parameters

distName – (String) the short, medium, or long name of the desired distribution to use
x_value – (Double) the x value to compute the PDF with respect to
scale – (Double) the scale of the computed PDF

Return type

Double

CEIL(a)

Rounds {a} up to the nearest integer.

Parameters: a – (Double) A number.
Return type: Double

Examples

CEIL(1.1)

2.0

COALESCE(object[, ...objects])

Return the first non-empty value from a list of arguments {object}, {…objects}, null otherwise.

Parameters

object – (Object) A boolean, string, number, array, or map.
...objects – (Object) Any number of additional comma-separated parameters of the appropriate type.

Return type

Object

CONCAT(a, b[, ...n])

Concatenates the Java toString() of {a}, {b}, {…n}. Returns null if any parameter is null.

Parameters

a – (Object) A boolean, string, number, array, or map.
b – (Object) A boolean, string, number, array, or map.
...n – (Object) Any number of additional comma-separated parameters of the appropriate type.

Return type

String

Examples

CONCAT('H','E','L','L','O',' ','W','O','R','L','D','!')

"HELLO WORLD!"

CONCAT_WS(separator, a, b[, ...n])

Uses a {separator} and concatenates the Java toString() of {a}, {b}, {…n}. Returns null if any argument is null.

Parameters

separator – (String) String used to separate the arguments.
a – (Object) A boolean, string, number, array, or map.
b – (Object) A boolean, string, number, array, or map.
...n – (Object) Any number of additional comma-separated parameters of the appropriate type.

Return type

String

Examples

CONCAT_WS(' ', 'HELLO', 'WORLD', 'YAL!')

"HELLO WORLD YAL!"

COS(r)

Returns the cosine of an angle.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

Description here for Returns the trigonometric cosine

COS(PI())

-1

COSH(r)

Returns the hyperbolic cosine of an angle.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

COSH(0.5)

1.1276259652063807

COUNT_UNIQ(collection)

Counts the number of unique items in the collection. Returns a map where the keys are the elements in the input collection, and the value is the count of the number of times each element appeared. Nulls are ignored

Parameters: collection – (Object) A list of objects.
Return type: Map

Examples

COUNT_UNIQ([1, 1, 3, 3])

{"1": 2, "3": 2}

DATA_SUFFICIENT_RATE(n, d[, limit])

DEPRECATED: Return the ratio ({n}/{d}) if the ratio of ( moe({n}, {d}) / ({n}/{d}) ) is less than or equal to the {limit}, null otherwise.

Parameters

n – (Double) A number.
d – (Double) A number.
limit – (Double) A number.

Return type

Double

DATE(timestamp)

Converts a {timestamp} into a string of the form yyyy-MM-dd.

Parameters: timestamp – (Long) Unix UTC timestamp.
Return type: String

DATETIME(timestamp)

Converts a {timestamp} into a string of the form yyyy-MM-dd HH:mm:ss.

Parameters: timestamp – (Long) Unix UTC timestamp.
Return type: String

DATE_FLOOR(timestamp)

returns a DateTime object with time at start of day.

Parameters: timestamp – (Object) a datetime or epoch timestamp object
Return type: DateTime

DAY_OF_WEEK(a)

Tries to cast {a} into a DateTime and then return the integer day of the week where [Monday - Sunday] maps to [1 - 7]. Throws an exception on cast failure.

Parameters: a – (Object) Any object to cast to a DateTime.
Return type: Integer

ENUM_BUCKET(lookup, enum[, default])

Return the array index of {lookup} in {enum}, otherwise return {default}.

Parameters

lookup – (String) String to bucket.
enum – (String[]) Enum as a list of strings.
default – (Double) Index to return if not found.

Return type

Double

EVENT_VAR(name)

returns the value of the expression associated with this object that was precomputed: once per event, or null if the variable does not exist. Event variables can be defined in TQL using query.event_var(‘name’, ‘expression’)

Parameters: name – (String) the name of the event variable to return the value of
Return type: Object

EXP(n)

Returns Euler’s constant (~2.71828) to the {n}th power.

Parameters: n – (Double) A number.
Return type: Double

Examples

EXP(1) - 1

1.718281828459045

EXPM1(n)

Returns Euler’s constant (~2.71828) to the {n}th power minus 1. This provides greater accuracy for small values of {n} than calculating the value yourself due to quirks in double-precision mathematics.

Parameters: n – (Double) A number.
Return type: Double

Examples

EXPM1(1)

1.718281828459045

EXTRACT_DOMAIN(a)

Extract domain {a} from URL as a string.

Parameters: a – (Object) A string.
Return type: String

Notes

This function implements the standard Java methodology

Examples

EXTRACT_DOMAIN('https://foo.bar.baz.example.com/path/file.html?q=val#hash=val')

"example.com"

FILTER(list, filter, break)

Return the list of values after {filter} is applied to each element of {list}.

Parameters

list – (Object[]) A boolean, string, number, array, or map.
filter – (Function) An anonymous function that evaluates to a truthy or falsey value.
break – (Function) An anonymous function that evaluates to a truthy or falsey value. If true, terminates the filter

Return type

StreamOrList

Notes

The arg needs to be just a single character [a-zA-Z]

FILTER can be nested in-line (e.g. FILTER(FILTER())) but not as sub-expressions.

Examples

Check whether each item in a list meets a condition.

FILTER([1, 2, 3], (x) -> (x = 3))

[3]

FIRST_EVENT(type)

return the first event of the timeline.

Parameters: type – (String) (optional) The type of event to return
Return type: Event

FLATTEN(array)

Return {array} flattened by one level.

Parameters: array – (Object[]) An array or iterable.
Return type: List

FLOOR(a)

Rounds {a} down to the nearest integer.

Parameters: a – (Double) A number.
Return type: Double

Examples

FLOOR(1.1)

1.0

FROM_UNIXTIME(timestamp[, date_format])

Converts a date from a Unix {timestamp} to a UTC time string using a {date_format}.

Parameters

timestamp – (Long) A Unix timestamp as a Long.
date_format – (String) A constant date format string.

Return type

String

Examples

FROM_UNIXTIME(NOW())

"2020-05-19 03:22:07"

GET_PROPERTY([variable, ]path)

retrieves the property corresponding to the given dot notation path ‘a.b’, or null if the property value is null.

Parameters

variable – (Object) Optional variable to get from instead of default object
path – (Object) a dot notation path without ${} notation

Return type

Object

GLOBAL_VAR(name)

returns the value of the expression associated with this object that was precomputed once per query, or null if the variable does not exist. Global variables can be defined in TQL using query.global_var(‘name’, ‘expression’). The global variable ‘timeline_stats’ is pre-definedfor all queries as a dictionary/map object with the following keys: [min_timestamp,max_timestamp,timeline_count,event_count,event_min_timestamp,event_max_timestamp,event_count_min,event_count_max,event_counts_by_type,time_series_min_max_timestamps]

Parameters: name – (String) the name of the global variable to return the value of
Return type: Object

HASH(s)

Returns a hash of {s}.

Parameters: s – (String) A string.
Return type: Integer

Examples

HASH('foo')

101574

ICDF(distName, x_value, scale)

returns the inverse cumulative distribution function (CDF) of the given x_value and scale parameters, using the provided distribution.

Supported distributions:

positive-support distributions (short-form abbreviations): exponential (e, exp), uniform (u, unif), triangular (t, tri), half-normal (h, hnorm), and half-logistic (l, hlog).

positive- & negative-support distributions are the symmetric analogs of the positive-support distributions: laplace (a, lap), rectangular (r, rect), symmetric triangular (s, stri), normal (n, norm), and logistic (o, log).

time-independent “constant” distribution (c, const) is also useful for various use cases.

Parameters

distName – (String) the short, medium, or long name of the desired distribution to use
x_value – (Double) the x value to compute the PDF with respect to
scale – (Double) the scale of the computed PDF

Return type

Double

IF(expr, a, b)

Return {a} if {expr} is true, otherwise return {b}.

Parameters

expr – (Object) Expression to evaluate.
a – (Object) Value to return if the expression is truthy.
b – (Object) Value to return if the expression is falsey.

Return type

Object

IFRETURN(expr, a)

Return {a} if {expr} is true otherwise do nothing

Parameters

expr – (Object) Expression to evaluate.
a – (Object) Value to return if the expression is truthy.

Return type

void

INT32(a)

Identical to TO_INT({a}).

Parameters: a – (Object) A boolean, string, number, array, or map.
Return type: Integer

JSON(object)

Returns the JSON representation of {object}.

Parameters: object – (Object) Generally something found in a MLRequest data path.
Return type: String

Examples

Description here for Return a JSON {object} converted to a string.

JSON(["a", "b", "c"])

"[\"a\",\"b\",\"c\"]"

JSON_FROM_LIST(a, b[, ...n])

Creates a JSON string with the Java toString() of {a}, {b}, {…n}. Must have an even amount of parameters representing key:value pairs

Parameters

a – (Object) A boolean, string, number, array, or map.
b – (Object) A boolean, string, number, array, or map.
...n – (Object) Any number of additional comma-separated parameters of the appropriate type.

Return type

String

Examples

Useful to dump the value of one or more expressions into JSON

JSON_FROM_LIST('pi', PI())

"{\"pi\":3.141592653589793}"

JSON_MAP_VALUE(string, key)

Return the value of a {key} from a JSON {string}.

Parameters

string – (String) JSON object as a string.
key – (Object) Generally a string when indexing into a MLRequest data field.

Return type

Object

Examples

JSON_MAP_VALUE('{"key":"value"}','key')

"value"

JSON_TO_MAP(string)

Convert a JSON string into a Map/dictionary type object.

Parameters: string – (String) JSON object as a string.
Return type: Map

LAST_EVENT(type)

return the last event of the timeline.

Parameters: type – (String) (optional) The type of event to return
Return type: Event

LIST(list, function[, break])

Return a {list} transformed via a {function} called on each element.

Parameters

list – (Object[]) A list.
function – (Function) A function taking 1 parameter.
break – (Function) Function that takes 2 parameters, the first being the ” + “accumulated value thus far and the second being the current element and terminates the reduce if true.

Return type

StreamOrList

LIST_REVERSE(list)

Returns the list or array in reverse order

Parameters: list – (Object) A list or array or string object.
Return type: List

LIST_TO_MAP(list)

Returns a map where the keys are the indices from {list} (beginning with 0) and the values are the elements of {list}.

Parameters: list – (Object[]) A list of objects.
Return type: Map

LIST_VALUE(list, idx)

Return the value of a {idx} in a {array or list or string}. Returns null if either is null or the index is out of bounds. If index is negative, it is from the end of the list or string

Parameters

list – (Object) A list or array or string object.
idx – (Object) A boolean, string, number, array, or map.

Return type

Object

Examples

LIST_VALUE([1,2,3], 1)

2

LOG(number, base)

Return the logarithm of a {number} for a given {base}. Any null, a base of 0, or a base of 1 will return null.

Parameters

number – (Double) A number.
base – (Double) A number.

Return type

Double

LOG10(a)

Returns the base 10 logarithm of {a}.

Parameters: a – (Double) A number.
Return type: Double

Examples

LOG10(POW(10,2))

2.0

LOG1P(a)

Returns the natural logarithm of the sum of the {a} and 1. This provides greater accuracy for small values of {n} than calculating the value yourself due to quirks in double-precision mathematics.

Parameters: a – (Double) A number.
Return type: Double

Examples

LOG1P(0.01)

0.009950330853168083

LOG2(a)

Returns the base 2 logarithm of {a}.

Parameters: a – (Double) A number.
Return type: Double

Examples

LOG2(POW(2,10))

10.0

LOWER(string)

Return a {string} converted to lowercase.

Parameters: string – (String) A string.
Return type: String

Examples

UPPER('ABC')

"abc"

MAP(list, function[, break])

Return a {list} transformed via a {function} called on each element.

Parameters

list – (Object[]) A list.
function – (Function) A function taking 1 parameter.
break – (Function) Function that takes 2 parameters, the first being the ” + “accumulated value thus far and the second being the current element and terminates the reduce if true.

Return type

StreamOrList

Examples

MAP([1, 2, 3], (x) -> (TO_STRING(x)))

['1', '2', '3']

MAP_EXTRACT(key, delimiter, string)

Return the value of a {key} from a {map} using a {delimiter}. Returns an empty string if not found.

Parameters

key – (String) A string.
delimiter – (String) The string defining the pattern separating a key from a value.
string – (String) A string representing a map using the provided delimiter.

Return type

String

MAP_TO_LIST(map, function)

Return a list from a {map} transformed via an apply {function} called with each key/value pair.

Parameters

map – (Map) A map of key/value pairs.
function – (Function) A function taking 2 parameters.

Return type

List

MAP_VALUE(map, key)

Return the value of a {key} in a {map}. Returns null if either is null.

Parameters

map – (Map) A map object.
key – (String) A string.

Return type

Object

MAX(a, b[, ...n])

Return the maximum value of {a}, {b}, {…n} ignoring nulls.

Parameters

a – (Number) A number.
b – (Number) A number.
...n – (Number) Any number of additional comma-separated parameters of the appropriate type.

Return type

Number

Examples

MAX(1, 2, 3)

3.0

MAX_NS(a, b[, ...n])

Return the maximum value of {a}, {b}, {…n} ignoring nulls.

Parameters

a – (Number) A number.
b – (Number) A number.
...n – (Number) Any number of additional comma-separated parameters of the appropriate type.

Return type

Number

Examples

Since max(null) will return null

MAX_NS(1, 2, 3, LOG(1, 0))

3.0

MD5(string)

returns the MD5 hash of a {string}

Parameters: string – (String) A string.
Return type: String

MD5_LONG(string)

returns the MD5 hash of a {string} as a long value

Parameters: string – (String) A string.
Return type: Long

MD5_MOD(string, n)

Divide the BigInteger MD5 hash of a {string} by {n} and return the remainder.

Parameters

string – (String) A string.
n – (Double) A number.

Return type

Long

Examples

MD5_MOD('foo', 4000000)

3225896

MILLIS(datetime)

Converts a {datetime} object into a milliseconds timestamp (the number of milliseconds since epoch).

Parameters: datetime – (DateTime) A datetime object.
Return type: Long

MIN(a, b[, ...n])

Return the minimum value from {a}, {b}, {…n} ignoring nulls.

Parameters

a – (Number) A number.
b – (Number) A number.
...n – (Number) Any number of additional comma-separated parameters of the appropriate type.

Return type

Number

MIN_NS(a, b[, ...n])

Return the minimum value from {a}, {b}, {…n} ignoring nulls.

Parameters

a – (Number) A number.
b – (Number) A number.
...n – (Number) Any number of additional comma-separated parameters of the appropriate type.

Return type

Number

ML_BIN(UUID)

DEPRECATED: Given a {UUID} take the absolute value of its hash and mod it by 100.

Parameters: UUID – (UUID) A UUUID object or string.
Return type: Integer

MOE(n, d)

DEPRECATED: Return the value from the following: 1.96 * Math.sqrt({n}/{d} * (1 - {n}/{d}) / {d}). Returns null if either parameter is NaN or null, if d <= 0, if n < 0, or if n > d.

Parameters

n – (Double) A number.
d – (Double) A number.

Return type

Double

MONOTONICALLY_INCREASING_ID()

Return a JVM-wide monotonically increasing integer, starting at 0

Return type: Long

NATLOG(a)

Returns the natural logarithm (base e) of {a}.

Parameters: a – (Double) A number.
Return type: Double

Examples

NATLOG(1)

0.0

NEXTDOWN(d)

Returns the floating-point value adjacent to {d} in the direction of negative infinity.

Parameters: d – (Double) A number.
Return type: Double

NEXTUP(d)

Returns the floating-point value adjacent to {d} in the direction of positive infinity.

Parameters: d – (Double) A number.
Return type: Double

NEXT_EVENT(type)

return the next event (relative current) of the given type (optional). Returns null if current event is the last one.

Parameters: type – (String) (optional) the type of the event to return
Return type: Event

NOT(a, NOT, b)

Logically NOT {a}.

Parameters

a – (Double) A number.
NOT – (BoolNotFunction) The operator itself.
b – (Double) A number.

Return type

Boolean

NOW()

Return the current time in milliseconds.

Return type: Long

OR(a, OR, b)

Logically OR {a} with {b}.

Parameters

a – (Double) A number.
OR – (BoolOrFunction) The operator itself.
b – (Double) A number.

Return type

Boolean

PARSE_KERNEL(kernels)

returns a time kernel corresponding to a valid input string such as ‘5m’ or ‘3h’

Parameters: kernels – (String) single time kernel string such as 4h or 1d
Return type: IncrementalityKernel

PARSE_KERNELS(kernels)

returns a list of time kernel objects corresponding to the comma-separated list of time kernel strings, ex: ‘0.5m,4h,1d,3d’

Parameters: kernels – (String) a comma-separated list of time kernels
Return type: java.util.List<com.nanigans.nanml.util.IncrementalityKernel>

PDF(distName, x_value, scale)

returns the probability density function (PDF) of the given x_value and scale parameters, using the provided distribution.

Supported distributions:

positive-support distributions (short-form abbreviations): exponential (e, exp), uniform (u, unif), triangular (t, tri), half-normal (h, hnorm), and half-logistic (l, hlog).

positive- & negative-support distributions are the symmetric analogs of the positive-support distributions: laplace (a, lap), rectangular (r, rect), symmetric triangular (s, stri), normal (n, norm), and logistic (o, log).

time-independent “constant” distribution (c, const) is also useful for various use cases.

Parameters

distName – (String) the short, medium, or long name of the desired distribution to use
x_value – (Double) the x value to compute the PDF with respect to
scale – (Double) the scale of the computed PDF

Return type

Double

PI()

Return the double constant PI (3.14…)

Return type: Double

POISSON_RANDOM()

Return a value from apache commons math PoissonDistribution.sample() with a mean and std of 1

Return type: Double

Examples

POISSON_RANDOM()

2.0

POW(base, n)

Return the value of the {base} raised to the {n}th power.

Parameters

base – (Double) A number.
n – (Double) A number.

Return type

Double

Examples

POW(10,2)

100

PREDICT(model, column_name, counterfactual_value)

make a prediction with a model

Parameters

model – (Object) A model string type or number id.
column_name – (Object) (optional) A MLColumn name to replace or a dictionary of counterfactual key/value pairs
counterfactual_value – (Object) (optional) a counterfactual replacement column value if not using the two-arg dictionary version

Return type

Double

PREDICT_ENSEMBLE(model, column_name, counterfactual_value)

make a series of predictions from the given model with one or more estimates defined.

Parameters

model – (Object) A model string type or number id.
column_name – (Object) (optional) A MLColumn name to replace or a dictionary of counterfactual key/value pairs
counterfactual_value – (Object) (optional) a counterfactual replacement column value if not using the two-arg dictionary version

Return type

List

PREVIOUS_EVENT(type)

return the previous event (relative current) of the given type (optional). Returns null if current event is the first one.

Parameters: type – (String) (optional) the type of the event to return
Return type: Event

RANDOM()

Return a value from Java’s Math.random().

Return type: Double

Examples

RANDOM()

0.47120533745848614

RANGE(start, end)

Return an integer array from {start} to {end}. Return an empty list if either value is null or end <= start. Takes the integer part of the parameters if they are not already integers.

Parameters

start – (Double) A number.
end – (Double) A number.

Return type

List

Examples

RANGE(0,5)

[0, 1, 2, 3, 4]

REDUCE(array, function[, function])

Return a scalar from an {array} reduced via a collector {function}.

Parameters

array – (Object[]) An array.
function – (Function) Function that takes 2 parameters, the first being the accumulated value thus far and the second being the current element.
function – (Function) Function that takes 2 parameters, the first being the accumulated value thus far and the second being the current element and terminates the reduce if true.

Return type

Object

Examples

REDUCE([1, 2, 3], (s, i) -> (s + i))

6

REGEX_EXTRACT(string, regex, n)

Return the {n}th group of the {regex} matched on a {string}. Returns an empty string if not found.

Parameters

string – (String) A string.
regex – (String) A regex pattern.
n – (Double) A number.

Return type

String

Examples

REGEX_EXTRACT('abcd', '([a-z])', 1)

'a'

REGEX_EXTRACT_ALL(string, regex)

Return a list of matches from the {string} for the first matching group of the {regex}. Returns an empty list if not found.

Parameters

string – (String) A string.
regex – (String) A regex pattern.

Return type

List

Examples

REGEX_EXTRACT_ALL('abcd', '([a-z])')

['a', 'b', 'c', 'd']

REGEX_REPLACE(string, replacements)

Return a {string} after doing all substitutions as defined in the {replacements} array. Return an empty string if the given string is null.

Parameters

string – (String) A string.
replacements – (String[]) An array describing regex replacements. Even index strings are regex patterns and odd index strings are replacements. The replacements occur directly after their corresponding regex pattern.

Return type

String

Examples

REGEX_REPLACE('my_search_string',['^.*search.*$','REPLACED'])

"REPLACED"

REPLACE_BLACKLIST(string)

Return a {string} with blacklist characters (anything except a-zA-Z0-9_ and -) replaced with _

Parameters: string – (String) A string.
Return type: String

Examples

REPLACE_BLACKLIST('something#odd')

'something_odd'

RNG(seed, distribution)

Return a generator that can generate random numbers, optionally specifying a seed, and a distribution.

Simple Usage: rng = RNG(); ${@rng.next} Usage With Args: rng = RNG(‘a seed’, ‘EXPONENTIAL’); ${@rng.next} Repeated Usage: RNG(); LIST(RANGE(0,100), (x) -> ${@rng.next})

Supported distributions:

positive-support distributions (short-form abbreviations): exponential (e, exp), uniform (u, unif), triangular (t, tri), half-normal (h, hnorm), and half-logistic (l, hlog).

positive- & negative-support distributions are the symmetric analogs of the positive-support distributions: laplace (a, lap), rectangular (r, rect), symmetric triangular (s, stri), normal (n, norm), and logistic (o, log).

time-independent “constant” distribution (c, const) is also useful for various use cases.

Parameters

seed – (Object) A seed value (can be any object)
distribution – (String) a distribution function (E[XP[ONENTIAL]], U[NIF[ORM]], N[ORM[AL]])

Return type

RNG

ROUND(n)

Return the nearest long integer to {n}.

Parameters: n – (Double) A number.
Return type: Double

Examples

ROUND(1234.56789)

1235

SAMPLE(distribution)

generate a random number from the given distribution. Short, medium, or long names are acceptable.

Supported distributions:

positive-support distributions (short-form abbreviations): exponential (e, exp), uniform (u, unif), triangular (t, tri), half-normal (h, hnorm), and half-logistic (l, hlog).

positive- & negative-support distributions are the symmetric analogs of the positive-support distributions: laplace (a, lap), rectangular (r, rect), symmetric triangular (s, stri), normal (n, norm), and logistic (o, log).

time-independent “constant” distribution (c, const) is also useful for various use cases.

Parameters: distribution – (String) A string.
Return type: Double

SAMPLE_BETA(alpha, beta)

Return a random value from a beta distribution defined by {alpha} and {beta}.

Parameters

alpha – (Double) A number.
beta – (Double) A number.

Return type

Double

Examples

SAMPLE_BETA(0.5, 2)

0.7490045585589136

SET_PROPERTY(...n)

set an attribute addressed by the given dot notation path (ex. ‘a.b’) to the specified value. Unlike most other functions, the SET_PROPERTY() function does not return a value. Example usage:: SET_PROPERTY(‘a.b’, ‘value’) SET_PROPERTY(‘a.b’, ‘value1’, ‘c.d’, ‘value2’, …) SET_PROPERTY(${@var}, ‘a.b’, ‘value1’, ‘c.d’, ‘value2’, …) where var is an event other timeline object

Parameters: ...n – (Object) Any number of additional comma-separated parameters of the appropriate type.
Return type: void

SIN(r)

Returns the sine of an angle.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

SIN(PI()/2)

1.0

SINH(r)

Returns the hyperbolic sine of an angle.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

SINH(0.5)

0.5210953054937474

SIZE(object)

Return the number of key/value pairs if {object} is a map, return the number of elements if {object} is a list, and return null otherwise.

Parameters: object – (Object) A boolean, string, number, array, or map.
Return type: Double

SORT(collection)

Sorts the collection ascending and returns it. Handles maps, lists, or arrays. Numbers sort before Strings in mixed types lists. The lists and arrays are sorted in place and returned. A map is returned (unless the input was already sorted). Maps are converted to sorted maps and so are permanently sorted. If items are inserted after the sort, the map is still sorted.

Parameters: collection – (Object) A list, array or map object.
Return type: Object

Examples

SORT([3, 2, 1])

[1, 2, 3]

SQRT(d)

Returns the positive square root of {d}.

Parameters: d – (Double) A number.
Return type: Double

STDEV(values)

Return the standard deviation of a list of numeric elements. If a single numeric element is passed, it is returned back. If a non-numeric element or null value is processed, null is returned.

Parameters: values – (Object) A list of values to take the standard deviation
Return type: Double

STRING_SPLIT(string, pattern)

Split a {string} and return list of strings

Parameters

string – (String) A string.
pattern – (String) Regex pattern to split the string

Return type

List

Examples

Description here for Split a {string} and return list of strings

STRING_SPLIT('foo_bar_baz', '_')

['foo', 'bar', 'baz']

SUM(values)

Return the sum of a list of numeric elements. If a single numeric element is passed, it is returned back. If a non-numeric element or null value is processed, null is returned.

Parameters: values – (Object) A list of values to sum up
Return type: Double

Examples

SUM([1, 1])

2

SUM_OPPORTUNITIES(value[, function])

Applies the entire preceding expression to a list of events defined by the ‘opportunity_filter’ and aggregates via a time-difference weighted categorical-grouped sum. Approximately, categorical, SUM(f(time_difference) * numerical) GROUP BY categorical, time_difference = ${@outcome.timestamp} - ${@timestamp}. Categorical gets expanded by ${@kernels} which defaults to ‘5m,15m,1h,4h,1d,3d,7d’. time_difference is the difference between the opportunity filter events ${@outcome.timestamp} and the sampled record event ${timestamp}. The function f() is referred to as a ‘kernel’ that distributes the opportunity’s impact over time, typically the uniform or exponential distribution.

Supported distributions:

positive-support distributions (short-form abbreviations): exponential (e, exp), uniform (u, unif), triangular (t, tri), half-normal (h, hnorm), and half-logistic (l, hlog).

positive- & negative-support distributions are the symmetric analogs of the positive-support distributions: laplace (a, lap), rectangular (r, rect), symmetric triangular (s, stri), normal (n, norm), and logistic (o, log).

time-independent “constant” distribution (c, const) is also useful for various use cases.

See additional documentation for more details of custom parameters that can be set.

Parameters

value – (Object) TBE
function – (Function) TBE

Return type

List

TAN(r)

Returns the tangent of an angle.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

TAN(PI()*(-1/4))

-0.9999999999999999

TANH(r)

Returns the hyperbolic tangent of an angle.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

TANH(0.5)

0.46211715726000974

TAU()

Return the double constant TAU (2 * PI)

Return type: Double

TIC(tickerName)

Creates a global ticker in context, with the provided name {a}.

Parameters: tickerName – (String) Name of the ticker.
Return type: Object

TIMELINE_VAR(name)

returns the value of the expression associated with this object that was precomputed: once per timeline, or null if the variable does not exist. Timeline variables can be defined in TQL using query.timeline_var(‘name’, ‘expression’)

Parameters: name – (String) the name of the timeline variable to return the value of
Return type: Object

TOC(tickerName)

Return time in MicroSeconds, since the ticker {a} was started by calling tic(“a”)

Parameters: tickerName – (String) Name of the ticker.
Return type: Long

TODEGREES(r)

Converts an angle measured in radians to an approximately equivalent angle measured in degrees.

Parameters: r – (Double) An angle in radians
Return type: Double

Examples

TODEGREES(PI())

180.0

TORADIANS(d)

Converts an angle measured in degrees to an approximately equivalent angle measured in radians.

Parameters: d – (Double) An angle in degrees
Return type: Double

Examples

TORADIANS(180)

3.141592653589793

TO_DATETIME(a)

Return {a} converted into a datetime.

Parameters: a – (Object) a string (yyyy-MM-dd HH:mm:ss, yyyy-MM-dd prefered) or number (ms since epoch)
Return type: DateTime

TO_DOUBLE(a)

Return {a} converted into an double.

Parameters: a – (Object) A boolean, string, number, array, or map.
Return type: Double

TO_INT(a)

Return {a} converted into an integer.

Parameters: a – (Object) A boolean, string, number, array, or map.
Return type: Integer

TO_STRING(a)

Return {a} converted into a string.

Parameters: a – (Object) A boolean, string, number, array, or map.
Return type: String

Examples

TO_STRING(100.001)

"100.001"

ULP(d)

Returns the value of the unit in last place of {d}. An ulp, unit in the last place, of a double value is the positive distance between this value and the double value next larger in magnitude.

Parameters: d – (Double) A number.
Return type: Double

UPPER(string)

Return a {string} converted to uppercase.

Parameters: string – (String) A string.
Return type: String

Examples

UPPER('abc')

"ABC"

VAR(values)

Return the variance of a list of numeric elements. If a single numeric element is passed, it is returned back. If a non-numeric element or null value is processed, null is returned.

Parameters: values – (Object) A list of values to take the variance of
Return type: Double

YEAR(timestamp)

Return the year of a milliseconds {timestamp}.

Parameters: timestamp – (Long) Number of milliseconds since epoch.
Return type: Long

Examples

YEAR(MILLIS(TO_DATETIME("2020-05-19 03:17:02.000")))

2020

UDFs 

You can extend the native functions library by writing your own UDFs.

For more information on UDFs, refer to the UDF guides here: User-Defined Functions (UDFs)

Functions

Built-ins

UDFs

Built-ins 

UDFs 