# Kapacitor TICKscript lambda expressions

This page documents an earlier version of Kapacitor. Kapacitor v1.6 is the latest stable version. View this page in the v1.6 documentation.

# Overview

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 nanoseconds units. Strings are converted to duration of the form as duration literals in TICKscript.

```
duration(value) 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

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.

Function | Description |
---|---|

`minute(t time) int64` |
the minute within the hour: range [0,59] |

`hour(t time) int64` |
the hour within the day: range [0,23] |

`weekday(t time) int64` |
the weekday within the week: range [0,6], 0 is Sunday |

`day(t time) int64` |
the day within the month: range [1,31] |

`month(t time) int64` |
the month within the year: range [1,12] |

`year(t time) int64` |
the year |

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.

#### Math functions

The following mathematical functions are available. Each function is implemented via the equivalent Go function.

Function | Description |
---|---|

abs(x float64) float64 | Abs returns the absolute value of x. |

acos(x float64) float64 | Acos returns the arccosine, in radians, of x. |

acosh(x float64) float64 | Acosh returns the inverse hyperbolic cosine of x. |

asin(x float64) float64 | Asin returns the arcsine, in radians, of x. |

asinh(x float64) float64 | Asinh returns the inverse hyperbolic sine of x. |

atan(x float64) float64 | Atan returns the arctangent, in radians, of x. |

atan2(y, x float64) float64 | Atan2 returns the arc tangent of y/x, using the signs of the two to determine the quadrant of the return value. |

atanh(x float64) float64 | Atanh returns the inverse hyperbolic tangent of x. |

cbrt(x float64) float64 | Cbrt returns the cube root of x. |

ceil(x float64) float64 | Ceil returns the least integer value greater than or equal to x. |

cos(x float64) float64 | Cos returns the cosine of the radian argument x. |

cosh(x float64) float64 | Cosh returns the hyperbolic cosine of x. |

erf(x float64) float64 | Erf returns the error function of x. |

erfc(x float64) float64 | Erfc returns the complementary error function of x. |

exp(x float64) float64 | Exp returns e**x, the base-e exponential of x. |

exp2(x float64) float64 | Exp2 returns 2**x, the base-2 exponential of x. |

expm1(x float64) float64 | Expm1 returns e**x - 1, the base-e exponential of x minus 1. It is more accurate than Exp(x) - 1 when x is near zero. |

floor(x float64) float64 | Floor returns the greatest integer value less than or equal to x. |

gamma(x float64) float64 | Gamma returns the Gamma function of x. |

hypot(p, q float64) float64 | Hypot returns Sqrt(pp + qq), taking care to avoid unnecessary overflow and underflow. |

j0(x float64) float64 | J0 returns the order-zero Bessel function of the first kind. |

j1(x float64) float64 | J1 returns the order-one Bessel function of the first kind. |

jn(n int64, x float64) float64 | Jn returns the order-n Bessel function of the first kind. |

log(x float64) float64 | Log returns the natural logarithm of x. |

log10(x float64) float64 | Log10 returns the decimal logarithm of x. |

log1p(x float64) float64 | Log1p returns the natural logarithm of 1 plus its argument x. It is more accurate than Log(1 + x) when x is near zero. |

log2(x float64) float64 | Log2 returns the binary logarithm of x. |

logb(x float64) float64 | Logb returns the binary exponent of x. |

max(x, y float64) float64 | Max returns the larger of x or y. |

min(x, y float64) float64 | Min returns the smaller of x or y. |

mod(x, y float64) float64 | Mod returns the floating-point remainder of x/y. The magnitude of the result is less than y and its sign agrees with that of x. |

pow(x, y float64) float64 | Pow returns x**y, the base-x exponential of y. |

pow10(x int64) float64 | Pow10 returns 10**e, the base-10 exponential of e. |

sin(x float64) float64 | Sin returns the sine of the radian argument x. |

sinh(x float64) float64 | Sinh returns the hyperbolic sine of x. |

sqrt(x float64) float64 | Sqrt returns the square root of x. |

tan(x float64) float64 | Tan returns the tangent of the radian argument x. |

tanh(x float64) float64 | Tanh returns the hyperbolic tangent of x. |

trunc(x float64) float64 | Trunc returns the integer value of x. |

y0(x float64) float64 | Y0 returns the order-zero Bessel function of the second kind. |

y1(x float64) float64 | Y1 returns the order-one Bessel function of the second kind. |

yn(n int64, x float64) float64 | Yn returns the order-n Bessel function of the second kind. |

#### String functions

The following string manipulation functions are available. Each function is implemented via the equivalent Go function.

Function | Description |
---|---|

strContains(s, substr string) bool | StrContains reports whether substr is within s. |

strContainsAny(s, chars string) bool | StrContainsAny reports whether any Unicode code points in chars are within s. |

strCount(s, sep string) int64 | StrCount counts the number of non-overlapping instances of sep in s. If sep is an empty string, Count returns 1 + the number of Unicode code points in s. |

strHasPrefix(s, prefix string) bool | StrHasPrefix tests whether the string s begins with prefix. |

strHasSuffix(s, suffix string) bool | StrHasSuffix tests whether the string s ends with suffix. |

strIndex(s, sep string) int64 | StrIndex returns the index of the first instance of sep in s, or -1 if sep is not present in s. |

strIndexAny(s, chars string) int64 | StrIndexAny returns the index of the first instance of any Unicode code point from chars in s, or -1 if no Unicode code point from chars is present in s. |

strLastIndex(s, sep string) int64 | StrLastIndex returns the index of the last instance of sep in s, or -1 if sep is not present in s. |

strLastIndexAny(s, chars string) int64 | StrLastIndexAny returns the index of the last instance of any Unicode code point from chars in s, or -1 if no Unicode code point from chars is present in s. |

strLength(s string) int64 | StrLength returns the length of the string. |

strReplace(s, old, new string, n int64) string | StrReplace returns a copy of the string s with the first n non-overlapping instances of old replaced by new. |

strSubstring(s string, start, stop int64) string | StrSubstring returns a substring based on the given indexes, strSubstring(str, start, stop) is equivalent to str[start:stop] in Go. |

strToLower(s string) string | StrToLower returns a copy of the string s with all Unicode letters mapped to their lower case. |

strToUpper(s string) string | StrToUpper returns a copy of the string s with all Unicode letters mapped to their upper case. |

strTrim(s, cutset string) string | StrTrim returns a slice of the string s with all leading and trailing Unicode code points contained in cutset removed. |

strTrimLeft(s, cutset string) string | StrTrimLeft returns a slice of the string s with all leading Unicode code points contained in cutset removed. |

strTrimPrefix(s, prefix string) string | StrTrimPrefix returns s without the provided leading prefix string. If s doesn’t start with prefix, s is returned unchanged. |

strTrimRight(s, cutset string) string | StrTrimRight returns a slice of the string s, with all trailing Unicode code points contained in cutset removed. |

strTrimSpace(s string) string | StrTrimSpace returns a slice of the string s, with all leading and trailing white space removed, as defined by Unicode. |

strTrimSuffix(s, suffix string) string) | StrTrimSuffix returns s without the provided trailing suffix string. If s doesn’t end with suffix, s is returned unchanged. |

regexReplace(r regex, s, pattern string) string | RegexReplace replaces matches of the regular expression in the input string with the output string. For example regexReplace(/a(b*)c/, ‘abbbc’, ‘group is $1’) -> ‘group is bbb’. The original string is returned if no matches are found. |

#### 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, 'true', 'false'))
.as('value')
```

The value of the field `value`

in the above example will be the string `true`

or `false`

, 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)
```

Was this page helpful?

Thank you for your feedback!

#### Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Kapacitor and this documentation. To find support, use the following resources: