eval command overview

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.

Syntax

The required syntax is in bold.

eval

<field>=<expression> ["," <field>=<expression> ]...

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

See also

eval command

eval command syntax details

eval command usage

eval command examples

Functions

Overview of SPL2 eval functions

Related Information

Types of expressions in the SPL2 Search Manual