eval command usage

General

You must specify a field name for the results that are returned from your eval command expression. You can specify a name for a new field or for an existing field.

If the field name that you specify matches an existing field name, the values in the existing field are replaced by the results of the eval expression.

If you specify a name for a new field, the name can't be a reserved word. For a list of the reserved words, see Reserved words.

Numbers and strings can be assigned to fields, while booleans cannot be assigned. However you can convert booleans and nulls to strings using the tostring() function, which can be assigned to fields.

If you are using a search as an argument to the eval command and functions, you cannot use a saved search name; you must pass a literal search string or a field that contains a literal search string (like the 'search' field extracted from index=_audit events).

Boolean values

Some evaluation functions return a Boolean value, such as the in or isint functions. While you can use these functions with the where or WHERE clause in the from command without issue, the eval command is a different matter.

The eval command cannot accept a Boolean value directly. For functions that return a Boolean value, you must specify the function inside the another function, such as the if function, which can accept a Boolean value as an input.

Numeric calculations

During calculations, numbers are treated as double-precision floating-point numbers, subject to all the usual behaviors of floating point numbers. If the calculation results in the floating-point special value NaN(Not a Number), it is represented as "nan" in your results. The special values for positive and negative infinity are represented in your results as "inf" and "-inf" respectively. Division by zero results in a null field.

Rounding

Results are rounded to a precision appropriate to the precision of the input results. The precision of the results can be no greater than the precision of the least-precise input. For example, the following search has different precision for 0.2 in each of the calculations based on the number of zeros following the number 2:

|makeresults | eval decimal1=8.250 * 0.2, decimal2=8.250 * 0.20, decimal3=8.250 * 0.200, exact=8.250 * exact(0.2)

The results look like this:

_time	decimal1	decimal2	decimal3	exact
2022-09-02 21:53:30	2	1.7	1.65	1.650

If you want to return an arbitrary number of digits of precision, use the exact function, as shown the the last calculation in the search.

Long numbers

There are situations where the results of a calculation contain more digits than can be represented by a floating- point number. In those situations precision might be lost on the least significant digits. The limit to precision is 17 significant digits, or -253 +1 to 253 -1.

Significant digits

If a result returns a long number with more digits than you want to use, you can specify the number of digits to return using the sigfig function. See Example 2 of the sigfig(X) function examples.

Functions

You can use a wide range of functions with the eval command. See Overview of SPL2 eval functions.

Operators

The following table lists the basic operations you can perform with the eval command. For these evaluations to work, the values need to be valid for the type of operation. For example, with the exception of addition, arithmetic operations might not produce valid results if the values are not numerical. When concatenating values, Splunk software reads the values as strings, regardless of the value.

Type	Operator
Arithmetic	+ - * / %
Concatenation	+
Boolean	AND OR NOT XOR < > <= >=  != = == LIKE

Operators that produce numbers

• The plus ( + ) operator accepts two numbers for addition, or two strings for concatenation.
• The subtraction ( - ), multiplication ( * ), division ( / ), and modulus ( % ) operators accept two numbers.

Operators that produce strings

• The plus ( + ) operator concatenates both strings and number. You must include a space on either side of the plus ( + ) operator. Numbers are concatenated in their string represented form.

Operators that produce Booleans

• The AND, OR, and XOR operators accept two Boolean values.
• The <>, <=, !=, and == operators accept two numbers or two strings. The != and == operators accept two numbers or two strings. The single equal sign ( = ) is a synonym for the double equal sign ( ==).
• The LIKE operator accepts two strings. This is a pattern match similar to what is used in SQL. For example string LIKE pattern. The pattern operator supports literal text, a percent ( % ) character for a wildcard, and an underscore ( _ ) character for a single character match. For example, field LIKE "a%b_" matches any string starting with a, followed by anything, followed by b, followed by one character.

Field names

If a field name begins with a number, you must enclose it in single quotation marks.

To specify a field name with multiple words, you can either concatenate the words, or use single quotation marks when you specify the name. For example, to specify the field name "Account ID" you can specify 'AccountID' or 'Account ID'.

To specify a field name with special characters, such as a period, use single quotation marks. For example, to specify the field name First.Name use 'First.Name'.

Search event tokens

If you are using the eval command in search event tokens, some of the evaluation functions might be unavailable or have a different behavior.

Using wildcards

You can use wildcards to match characters in string values. With the eval command, you must use the like function.

• Use the percent ( % ) symbol as a wildcard for matching multiple characters
• Use the underscore ( _ ) character as a wildcard to match a single character

In this example, the eval command returns search results for values in the ipaddress field that start with 198.

... | eval specificIP = like (ipaddress, "198.%" )

See the like (<str>, <pattern>) function in the list of Comparison and Conditional eval functions.

Differences between SPL and SPL2

Field names with special character must be in single quotes

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

Version	Example 1	Example 2
SPL	eval something&strange = error	eval "spaced field" = "value"
SPL2	eval 'something&strange' = error	eval 'spaced field' = "value"

The concatenation operator is the plus ( + ) sign

In SPL2, the concatenation operator is the plus ( + ) sign. Use " " to include a space character as part of the concatenation.

Version	Example 1	Example 2
SPL	...eval fullName = firstName.lastName	...eval fullName = firstName" "." "lastName
SPL2	...eval fullName = firstName+lastName	...eval fullName = (firstName+" "+lastName)

Use literals for true, false, and null

In SPL2, the true(), false(), and null() functions are removed. Use the literals true, false, and null instead of the functions.

Version	Example
SPL	...eval description=case(status==200,"OK", status==404, "Not found", true(), "Other")
SPL2	... eval description=case(status==200,"OK", status==404, "Not found", true, "Other")

See also

eval command

eval command overview

eval command syntax details

eval command examples