Types of expressions

Expressions are widely used in SPL2. Expressions produce a value and can be composed of literals, functions, fields, parameters, comparisons and other expressions. You can use expressions with the following commands and clauses:

  • With the eval command to calculate or construct new values. For example: 
    ...| eval diameter=circumference/3.14
  • In a group by clause to specify a time span that is used for aggregation groups. For example: 
    ... GROUP BY span (_time, 3h)
  • With a predicate in the from and where commands to create a filter. For example: 
    | FROM orders WHERE availability="in stock" ...

You can combine literals or constants, variables such as fields, navigations or parameters, operators and functions to create expressions that can be used to fabricate new values or predicate expressions.

Note: These expressions are valid in commands that support expressions, with the exception of the search command. The search command has a different set of syntax rules.

Predicate expressions are a unique type of expression. See Predicate expressions.

Expressions quick reference

The following table describes the type of expressions that you can use with SPL2:

Expression type Description Examples Output
String literal

A regular string value. String values must be enclosed in double quotation marks.

You can use string templates in string literal expressions. See String templates in expressions. 

"surname"
"C:\\windows"
"C:\\windows\temp"
surname
C:\windows
C:\windows   emp
The \t in the path is interpreted as a tab.
Raw string literal

A string value in which the backslash character ( \ ) is not processed.

Raw string literals must be preceded by the at symbol ( @ ) and enclosed in double quotation marks. Double quotations inside the string must be escaped using double quotations. 

@"C:\windows"
@"C:\windows\temp"
@"C:\\test"
@"Leroy ""Satchel"" Paige"
@"\d.t"
 
C:\windows
C:\windows\temp
C:\\test
Leroy "Satchel" Paige
\d.t
Boolean literal A Boolean value. The only valid Boolean values are true and false. 
true
false
 
true
false
Search literal

One or more predicate values that you can specify wherever an expression is valid. The AND operator is implicit between the values. Search literals must be enclosed in backtick characters ( ` ).

See Search literals in expressions. 

|FROM main 
WHERE `500 ERROR`
... | stats count(`500`) by host
The output is the same as 
|FROM main 
WHERE `500` AND `ERROR`
... search 500 | stats count() by host
Number literal A number value or a numeric expression. 
2048
5-4
 
2048
1
Null literal A null value is the intentional absence of any object value. You can use a null literal to set a field to null, which removes the field. 
null
Array literal

An array of values or a multivalue field. Arrays are enclosed in square brackets. You can specify constant values and expressions in array literal expressions.

See Array and object literals in expressions.

See Access expressions for arrays and objects. 

[2,4,6,8]
... | eval a=10, value = [[1,2,3], a+2]
 
[2,4,6,8]
a=10 value=[[1,2,3],12]
Object literal

A list of comma-separated values enclosed in curly brackets. A SPL object literal is a convenient way to create JSON objects. To be JSON compatible, internally field names are stored with double quotation marks.

See Array and object literals in expressions.

See Access expressions for arrays and objects. 

{day: "mon", temp: 42}
[{type: "cooperative", 'game-name': "Forbidden Island"}, {type: "competitive", 'game-name': "Ticket to Ride"}]
 
{"day": "mon", "temp": 42}
[{"type": "cooperative", "game-name": "Forbidden Island"}, {"type": "competitive", "game-name": "Ticket to Ride"}]
Field

The name of a field in your data.

If a field name begins with anything other than a-z, A-Z, or the underscore ( _ ) character, you must enclose the field name in single quotation marks.

Field names that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in single quotation marks.

Field names cannot contain square brackets [ ].

You can use field templates in field expressions. See Field templates in expressions. 

client_ip
port
'5minutes'
'status-code'
avg(bytes/1024)
...| eval '${city}' = 456
When a field name is included in an expression, the field values are used when the expression is resolved.

The field name bytes is part of this binary expression.
The field template '${city}' is resolved when the eval command is processed.

Assignment

Uses the equal sign ( = ) to assign the results of an <expression> to a <field>. If the field exists in the incoming search results, the values in that field are replaced. Otherwise a field is created in the outgoing search results.

The syntax is:

<field>=<expression> 

speed=distance/time
'low-category' = lower(categoryId)
 
speed=65
'low-category' = arcade
Parameter reference A placeholder in a search string. A parameter reference always begins with a $ symbol. A value for that placeholder must be provided when you run the search. 
FROM weblogs WHERE status=$status
Function

A function call with one or more expressions.

The syntax is:

function_name ( <expression> [, <expression> ]... ) 

avg(size)
case(status = 200, "OK", status = 404, "Not found", status = 500, "Internal Server Error")
When a function is included in an expression, the results of the function are used when the expression is resolved.
Predicate An expression that returns either TRUE or FALSE. See Predicate expressions for descriptions and examples of valid predicates that you can use. 
true
false
Unary

An operation with only one argument. Primarily used with unary minus to change the sign of its argument. A positive number becomes a negative, and a negative number becomes a positive. Use a space between the sign and the argument.

The syntax is:

[ + | - ] <expression> 

- discount_amount
- (.20)
 
-discount_amount
-.20
Binary An operation with two arguments. A common binary expression is a + b, which is the addition operator ( + ) surrounded by two arguments, or operands.

The syntax is:

<expression> <binary-operator> <expression>

Valid binary operators are:

addition ( + )

subtraction ( - )

division ( / )

multiplication ( * )

percent ( % )

concatenation ( + ) 

5 + 12
bytes/1024
surname+", "+firstname
When a binary operation is included in an expression, the results of the operation are used when the expression is resolved.
Lambda

A function literal written in a concise form. A function literal is a function that is not declared but passed directly as an expression. Lambda expressions use the lambda symbol ( -> ).

Use a lambda expression as a parameter for a function. See Lambda expressions. 

( ) -> 1 + 2
$a -> $a + 10
$a -> { $z = 1; return $a + $z } 
($a, $b) -> $a + $b 
($a, $b) -> { $z = $a + $b; return $z }
($a) -> { $c=$a*2; $d=$a*4; return $c+$d }