Lambda expressions

TICKscript uses lambda expressions to define transformations on data points as well as define Boolean conditions that act as filters. Lambda expressions wrap mathematical operations, Boolean operations, internal function calls or a combination of all three. TICKscript tries to be similar to InfluxQL in that most expressions that you would use in an InfluxQL WHERE clause will work as expressions in TICKscript, but with its own syntax:

• All field or tag identifiers must be double quoted.
• The comparison operator for equality is == not =.

All lambda expressions in TICKscript begin with the lambda: keyword.

.where(lambda: "host" == 'server001.example.com')

In some nodes the results of a lambda expression can be captured into a new field as a named result using the property setter .as(). In this way they can be used in other nodes further down the pipeline.

The internal functions of lambda expressions can be either stateless or stateful. Stateful means that each time the function is evaluated the internal state can change and will persist until the next evaluation.

For example the built-in function sigma calculates a running mean and standard deviation and returns the number of standard deviations the current data point is away from the mean.

Example 1 – the sigma function

sigma("value") > 3.0

Each time that the expression is evaluated it updates the running statistics and then returns the deviation. The simple expression in Example 1 evaluates to false while the stream of data points it has received remains within 3.0 standard deviations of the running mean. As soon as a value is processed that is more than 3.0 standard deviations from the mean it evaluates to true. Such an expression can be used inside of a TICKscript to define powerful alerts, as illustrated in Example 2 below.

Example 2 – TICKscript with lambda expression

stream
    |from()
    ...
    |alert()
        // use an expression to define when an alert should go critical.
        .crit(lambda: sigma("value") > 3.0)

Note on inadvertent type casting

Beware that numerical values declared in the TICKscript follow the parsing rules for literals introduced in the Syntax document. They may not be of a suitable type for the function or operation in which they will be used. Numerical values that include a decimal will be interpreted as floats. Numerical values without a decimal will be interpreted as integers. When integers and floats are used within the same expression the integer values need to use the float() type conversion function if a float result is desired. Failure to observe this rule can yield unexpected results. For example, when using a lambda expression to calculate a ratio between 0 and 1 of type float to use in generating a percentage; and when the fields are of type integer, it might be assumed that a subset field can be divided by the total field to get the ratio( e.g. subset/total * 100). Such an integer by integer division will result in an integer value of 0. Furthermore multiplication of the result of such an operation by the literal 100 (an integer) will also result in 0. Casting the integer values to float will result in a valid ratio in the range between 0 and 1, and then multiplication by the literal 100.0 (a float) will result in a valid percentage value. Correctly written, such an operation should look like this:

eval(lambda: float("total_error_responses")/float("total_responses") * 100.0).

If in the logs an error appears of the type E! mismatched type to binary operator..., check to ensure that the fields on both sides of the operator are of the same and the desired type.

In short, to ensure that the type of a field value is correct, use the built-in type conversion functions (see below).

Built-in functions

Stateful functions

Count

Count takes no arguments but returns the number of times the expression has been evaluated.

count() int64

Sigma

Computes the number of standard deviations a given value is away from the running mean. Each time the expression is evaluated the running mean and standard deviation are updated.

sigma(value float64) float64

Spread

Computes the running range of all values passed into it. The range is the difference between the maximum and minimum values received.

spread(value float64) float64

Stateless functions

Type conversion functions

Bool

Converts a string into a Boolean via Golang’s strconv.ParseBool function. Numeric types can also be converted to a bool where a 0 -> false and 1 -> true.

bool(value) bool

Int

Converts a string or float64 into an int64 via Golang’s strconv.ParseInt or simple int64() coercion. Strings are assumed to be decimal numbers. Durations are converted into an int64 with nanoseconds units. A Boolean is converted to an int64 where false -> 0 and true -> 1.

int(value) int64

Float

Converts a string or int64 into an float64 via Golang’s strconv.ParseFloat or simple float64() coercion. A Boolean is converted to a float64 where false -> 0.0 and true -> 1.0.

float(value) float64

String

Converts a bool, int64 or float64 into an string via Golang’s strconv.Format* functions. Durations are converted to a string representation of the duration.

string(value) string

Duration

Converts an int64 or a float64 into an duration assuming the unit as specified as the 2nd argument Strings are converted to duration of the form as duration literals in TICKscript.

duration(value int64|float64, unit duration) duration
duration(value string) duration

Existence

IsPresent

Returns a Boolean value based on whether the specified field or tag key is present. Useful for filtering out data this is missing the specified field or tag.

|where(lambda: isPresent("myfield"))

This returns TRUE if myfield is a valid identifier and FALSE otherwise.

Time functions

The time field

Within each expression the time field contains the time of the current data point. The following functions can be used on the time field. Each function returns an int64.

Example usage:

lambda: hour("time") >= 9 AND hour("time") < 19

The above expression evaluates to true if the hour of the day for the data point falls between 0900 hours and 1900 hours.

Now

Returns the current time.

now() time

Example usage:

lambda: "expiration" < unixNano(now())

Math functions

The following mathematical functions are available. Each function is implemented via the equivalent Go function (linked in the table below for reference only).

String functions

The following string manipulation functions are available. Each function is implemented via the equivalent Go function (linked in the table below for reference only).

Example:

.where(lambda: !strContains("fstype", 'nfs') OR !strContains("fstype", 'cifs'))

Human string functions

HumanBytes

Converts an int64 or a float64 with units bytes into a human readable string representing the number of bytes.

humanBytes(value) string

Conditional functions

If

Returns the result of its operands depending on the value of the first argument. The second and third arguments must return the same type.

Example:

|eval(lambda: if("field" > threshold AND "field" != 0, 'high', 'normal'))
    .as('value')

The value of the field value in the above example will be the string high or normal, depending on the condition passed as the first argument.

The if function’s return type is the same type as its second and third arguments.

if(condition, true expression, false expression)