Scalar Functions and Operators

Scanner supports some functions and operators for scalar evaluation, i.e. direct evaluation of values. These are most commonly used in the eval function in the pipeline, and in detection alert templates.

In general, scalar operators and functions are meant to be used with particular types of inputs (e.g. arithmetic operators are intended to be used with numbers). If any of the inputs are of an incorrect type, the operation returns null instead.

Basic Syntax

Operators are standard unary or infix arithmetic and logical operators. Numbers are expressed as-is. Strings are delimited by double-quotes.

1 + 1 # => 2
-(2 * 3) # => -6
true and false # => false
not true # => false
"foo" # => "foo"

Scope values (i.e. column names) can be referenced using backticks, or using bare (i.e. unquoted) strings, however, bare strings cannot include the following characters: :()"'<>=|,~{}!#` , or be any reserved keyword.

# returns one fewer than the number of fenceposts
number_of_fenceposts - 1

# returns true iff a cat named Biscuit
`animal:species` == "cat" and name == "Biscuit"

Parentheses may be used to explicitly specify precedence:

(1 + 2) * 3 # => 9
(true or false) and false # => false

Infix operators must be separated from their operands with spaces. E.g.:

# Reads a value called `total_count` and subtracts 1 from it
total_count - 1
# Reads a value called `us_west-1` and doesn't subtract anything
us_west-1

Values are not implicitly cast to other types. Any operand that is the wrong type results in a null value. E.g. all of the following return null:

not 1
true and "false"
"cat" + "dog"

We support the following infix operators in scalar evaluation contexts:

Operator	Name	Behavior
+, -, *, /	Infix Arithmetic	If a and b are both numbers, then this returns the result of that arithmetic operation, e.g. a + b returns the sum of a and b. If a and bare not both numbers, this returns null.
==, !=	Equality	a == b returns true if a and b are value-equal, and false otherwise. != returns the inverse.
<, >, <=, >=	Ordered Comparison	This returns a truth value based on the ordering. If aand bare both strings, then this performs a lexical (i.e. alphabetical) comparison. E.g. "abc" < "bbc" would be true. If a and b are both numbers, then this performs a numerical comparison. E.g. 1 >= 1 would be true. Otherwise, this returns null.
and	Logical And	a and b returns true if a and b are both true boolean values, false if a and b are boolean but not true, and null otherwise.
or	Logical Or	a or b returns true if a and b are both boolean values and either is true, false if a and b are boolean but both not true, and null otherwise.
-	Unary Negation	-a returns the arithmetic negation of aif it is a number. Otherwise, it returns null.
not	Logical Not	not a returns the logical negation of a if it is a boolean value. I.e. it returns true if a is false and false if a is true. Otherwise, it returns null.

Operator precedence is, in descending order:

• all unary operators

• * /

• + -

• < > <= >= == !=

• and

• or

All operators are left-associative.

Scalar Functions

Scalar functions are invoked with the parentheses (). As is standard, arguments can be passed, and are delimited by commas ,.

# Computes the closest whole-number number of seconds
math.round(elapsed_ms / 1000)

# Resolves to a different string value based on the http status
if(`http.status` == 200, "OK", "Something went wrong")

See individual function documentation for more details.

Reserved Keywords

The following keywords are reserved in scalar expressions: null , false, true, as, by, and, or, not, let. Use backticks if you need to reference columns or values with those names.