eval command: Overview and syntax

The SPL2 eval command calculates an expression and puts the resulting value into a search results field.

  • If the field name that you specify does not match a field in the output, a new field is added to the search results.
  • If the field name that you specify matches a field name that already exists in the search results, the results of the eval expression overwrite the values in that field.

The eval command evaluates mathematical, string, and boolean expressions.

You can chain multiple eval expressions in one search using a comma to separate subsequent expressions. The search processes multiple eval expressions left-to-right and lets you reference previously evaluated fields in subsequent expressions.

Use these links to quickly navigate to the main sections in this topic:

How the SPL2 eval command works

Most of the time the SPL2 eval command is used to create a new field in your search results and the values in that new field are the result of an expression. There are many types of expressions you can specify.

Using mathematical expressions

One type of expression you can perform is a mathematical expression, such as multiplication, division, addition, and subtraction.

Suppose you want to divide the values in one field by the values in another field. This example creates a new field called velocity in each event and calculate the velocity by dividing the values in the distance field by the values in the time field. 

... | eval velocity=distance/time

Using eval functions

There are dozens of built-in functions that you can use in the eval expression. The functions are organized into these categories:

  • Comparison and Conditional functions
  • Conversion functions
  • Cryptographic functions
  • Date and Time functions
  • Informational functions
  • JSON functions
  • Mathematical functions
  • Multivalue eval functions
  • Statistical eval functions
  • Text functions
  • Trig and Hyperbolic functions

One common function is the if function. Suppose that you want to create a field called error and set the value in the error field to OK if the status value is 200. Otherwise set the error field value to Problem. 

... | eval error = if(status == 200, "OK", "Problem")

Separate events into categories and calculate the count, minimum, maximum for each category

This example uses recent earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that contains magnitude (mag), coordinates (latitude, longitude), region (place), and so forth, for each earthquake recorded.

Earthquakes occurring at a depth of less than 70 km are classified as shallow-focus earthquakes, while those with a focal-depth between 70 and 300 km are commonly termed mid-focus earthquakes. In subduction zones, deep-focus earthquakes may occur at much greater depths (ranging from 300 up to 700 kilometers).

To classify recent earthquakes based on their depth, you use the following search. 

FROM all_month | eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", depth>300, "Deep") | stats count() min(Mag) max(Mag) by Description

The eval command is used to create a field called Description, which takes the value of "Shallow", "Mid", or "Deep" based on the Depth of the earthquake. The case() function is used to specify which ranges of the depth fits each description. For example, if the depth is less than 70 km, the earthquake is characterized as a shallow-focus quake; and the resulting Description is Shallow.

The search also pipes the results of the eval command into the stats command to count the number of earthquakes and display the minimum and maximum magnitudes for each Description.

The results look something like this:

Description count min(Mag) max(Mag)
Deep 35 4.1 6.7
Mid 635 0.8 6.3
Shallow 6236 -0.60 7.70

Syntax

The required syntax is in bold.

eval

<assignment_expression> ["," <assignment_expression> ]...

To specify multiple evaluations, separate each <assignment_expression> with a comma.

Required arguments

assignment_expression

Syntax: <field>=<expression> [, <field>=<expression> ] ...

Description: The <field> is a destination field name for the result of the <expression>. If the field name already exists in your events, the eval command overwrites the values with the results of the <expression>. Otherwise the eval command creates a new field using <field>. The field name that you specify can't be a reserved word and can't include square brackets [ ]. See eval command usage.

The <expression> is a <string> which can be a combination of values, variables, operators, and functions that are processed to determine the value to place in the destination <field>.
  • The <expression> is case-sensitive. The syntax of the <expression> is checked before running the search, and an exception is returned for an invalid expression.
  • The result of an eval statement cannot be a Boolean. If, at search time, the <expression> cannot be evaluated successfully for a given event, the eval command erases the resulting field.
  • If the <expression> references a field name that contains non-alphanumeric characters, it needs to be surrounded by single quotation marks. For example, if the field name is server-1 you specify the field name like this ...| eval new=count+'server-1'.
  • If the <expression> references literal strings, the expression needs to be surrounded by double quotation marks. For example, if the string you want to use is server- you specify the string like this ...| eval new="server-"+host.