eval command usage
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).
Some evaluation functions return a Boolean value, such as the
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.
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.
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.
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:
| 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:
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.
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
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.
You can use a wide range of functions with the
eval command. See Overview of SPL2 eval functions.
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.
|Arithmetic||+ - * / %|
|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.
==operators accept two numbers or two strings. The
==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.
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
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
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.
You can use wildcards to match characters in string values. With the
eval command, you must use the
- 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
... | 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
null() functions are removed.
Use the literals
null instead of the functions.
|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")|
eval command syntax details
eval command examples
This documentation applies to the following versions of Splunk® Cloud Services: current