Evaluation functions
Use the evaluation functions to evaluate an expression, based on your events, and return a result.
Quick reference
See the Supported functions and syntax section for a quick reference list of the evaluation functions.
Commands
You can use evaluation functions with the eval
, fieldformat
, and where
commands, and as part of eval expressions with other commands.
Usage
- All functions that accept strings can accept literal strings or any field.
- All functions that accept numbers can accept literal numbers or any numeric field.
String arguments and fields
For most evaluation functions, when a string argument is expected, you can specify either a literal string or a field name. Literal strings must be enclosed in double quotation marks. In other words, when the function syntax specifies a string you can specify any expression that results in a string. For example, you have a field called name
that contains the names of your servers. If you want to append the literal string server
at the end of the name, you would use dot notation like this in your search: name."server"
.
Nested functions
You can specify a function as an argument to another function.
In the following example, the cidrmatch
function is used as the first argument in the if
function.
... | eval isLocal=if(cidrmatch("123.132.32.0/25",ip), "local", "not local")
The following example shows how to use the true()
function to provide a default to the case
function.
... | eval error=case(status == 200, "OK", status == 404, "Not found", true(), "Other")
Supported functions and syntax
There are two ways that you can see information about the supported evaluation functions:
Function list by category
The following table is a quick reference of the supported evaluation functions, organized by category. This table provides a brief description for each function. Use the links in the table to learn more about each function and to see examples.
Type of function | Supported functions and syntax | Description |
---|---|---|
Comparison and Conditional functions | case(<condition>,<value>,...) | Accepts alternating conditions and values. Returns the first value for which the condition evaluates to TRUE. |
cidrmatch(<cidr>,<ip>) | Returns TRUE when an IP address, <ip> , belongs to a particular CIDR subnet, <cidr> .
| |
coalesce(<values>) | Takes one or more values and returns the first value that is not NULL. | |
false() | Returns FALSE. | |
if(<predicate>,<true_value>,<false_value>) | If the <predicate> expression evaluates to TRUE, returns the <true_value> , otherwise the function returns the <false_value> .
| |
in(<field>,<list>) | Returns TRUE if one of the values in the list matches a value that you specify. | |
like(<str>,<pattern>) | Returns TRUE only if <str> matches <pattern> .
| |
lookup(<lookup_table>, <json_object>, <json_array>) | Performs a CSV lookup. Returns the output field or fields in the form of a JSON object. The | |
match(<str>, <regex>) | Returns TRUE if the regular expression <regex> finds a match against any substring of the string value <str> . Otherwise returns FALSE.
| |
null() | This function takes no arguments and returns NULL. | |
nullif(<field1>,<field2>) | Compares the values in two fields and returns NULL if the value in <field1> is equal to the value in <field2> . Otherwise returns the value in <field1> .
| |
searchmatch(<search_str>) | Returns TRUE if the event matches the search string. | |
true() | Returns TRUE. | |
validate(<condition>, <value>,...) | Takes a list of conditions and values and returns the value that corresponds to the condition that evaluates to FALSE. This function defaults to NULL if all conditions evaluate to TRUE. This function is the opposite of the case function.
| |
Conversion functions | ipmask(<mask>,<ip>) | Generates a new masked IP address by applying a mask to an IP address using a bitwise AND operation.
|
printf(<format>,<arguments>) | Creates a formatted string based on a format description that you provide. | |
tonumber(<str>,<base>) | Converts a string to a number. | |
tostring(<value>,<format>) | Converts the input, such as a number or a Boolean value, to a string. | |
Cryptographic functions | md5(<str>) | Computes the md5 hash for the string value. |
sha1(<str>) | Computes the sha1 hash for the string value. | |
sha256(<str>) | Computes the sha256 hash for the string value. | |
sha512(<str>) | Computes the sha512 hash for the string value. | |
Date and Time functions | now() | Returns the time that the search was started. |
relative_time(<time>,<specifier>) | Adjusts the time by a relative time specifier. | |
strftime(<time>,<format>) | Takes a UNIX time and renders it into a human readable format. | |
strptime(<str>,<format>) | Takes a human readable time and renders it into UNIX time. | |
time() | The time that eval function was computed. The time will be different for each event, based on when the event was processed. | |
Informational functions | isbool(<value>) | Returns TRUE if the field value is Boolean. |
isint(<value>) | Returns TRUE if the field value is an integer. | |
isnotnull(<value>) | Returns TRUE if the field value is not NULL. | |
isnull(<value>) | Returns TRUE if the field value is NULL. | |
isnum(<value>) | Returns TRUE if the field value is a number. | |
isstr(<value>) | Returns TRUE if the field value is a string. | |
typeof(<value>) | Returns a string that indicates the field type, such as Number, String, Boolean, and so forth | |
JSON functions | json_object(<members>) | Creates a new JSON object from members of key-value pairs. |
json_append(<json>, <path_value_pairs>) | Appends values to the ends of indicated arrays within a JSON document. | |
json_array(<values>) | Creates a JSON array using a list of values. | |
json_array_to_mv(<json_array>, <boolean>) | Maps the elements of a proper JSON array into a multivalue field. | |
json_extend(<json>, <path_value_pairs>) | Flattens arrays into their component values and appends those values to the ends of indicated arrays within a valid JSON document. | |
json_extract(<json>, <paths>) | This function returns a value from a piece JSON and zero or more paths. The value is returned in either a JSON array, or a Splunk software native type value. | |
json_extract_exact(<json>,<keys>) | Returns Splunk software native type values from a piece of JSON by matching literal strings in the event and extracting them as keys. | |
json_keys(<json>) | Returns the keys from the key-value pairs in a JSON object as a JSON array. | |
json_set(<json>, <path_value_pairs>) | Inserts or overwrites values for a JSON node with the values provided and returns an updated JSON object. | |
json_set_exact(<json>,<key_value_pairs>) | Uses provided key-value pairs to generate or overwrite a JSON object. | |
json_valid(<json>) | Evaluates whether piece of JSON uses valid JSON syntax and returns either TRUE or FALSE. | |
Mathematical functions | abs(<num>) | Returns the absolute value. |
ceiling(<num>) | Rounds the value up to the next highest integer. | |
exact(<expression>) | Returns the result of a numeric eval calculation with a larger amount of precision in the formatted output. | |
exp(<num>) | Returns the exponential function eN .
| |
floor(<num>) | Rounds the value down to the next lowest integer. | |
ln(<num>) | Returns the natural logarithm. | |
log(<num>,<base>) | Returns the logarithm of <num> using <base> as the base. If <base> is omitted, base 10 is used. | |
pi() | Returns the constant pi to 11 digits of precision. | |
pow(<num>,<exp>) | Returns <num> to the power of <exp>, <num><exp> .
| |
round(<num>,<precision>) | Returns <num> rounded to the amount of decimal places specified by <precision>. The default is to round to an integer. | |
sigfig(<num>) | Rounds <num> to the appropriate number of significant figures. | |
sqrt(<num>) | Returns the square root of the value. | |
sum(<num>,...) | Returns the sum of numerical values as an integer. | |
Multivalue eval functions | commands(<value>) | Returns a multivalued field that contains a list of the commands used in <value>. |
mvappend(<values>) | Returns a multivalue result based on all of values specified. | |
mvcount(<mv>) | Returns the count of the number of values in the specified field. | |
mvdedup(<mv>) | Removes all of the duplicate values from a multivalue field. | |
mvfilter(<predicate>) | Filters a multivalue field based on an arbitrary Boolean expression. | |
mvfind(<mv>,<regex>) | Finds the index of a value in a multivalue field that matches the regular expression. | |
mvindex(<mv>,<start>,<end>) | Returns a subset of the multivalue field using the start and end index values. | |
mvjoin(<mv>,<delim>) | Takes all of the values in a multivalue field and appends the values together using a delimiter. | |
mvmap(<mv>,<expression>) | This function iterates over the values of a multivalue field, performs an operation using the <expression> on each value, and returns a multivalue field with the list of results. | |
mvrange(<start>,<end>,<step>) | Creates a multivalue field based on a range of specified numbers. | |
mvsort(<mv>) | Returns the values of a multivalue field sorted lexicographically. | |
mvzip(<mv_left>,<mv_right>,<delim>) | Combines the values in two multivalue fields. The delimiter is used to specify a delimiting character to join the two values. | |
mv_to_json_array(<field>, <inver_types>) | Maps the elements of a multivalue field to a JSON array. | |
split(<str>,<delim>) | Splits the string values on the delimiter and returns the string values as a multivalue field. | |
Statistical eval functions | avg(<values>) | Returns the average of numerical values as an integer. |
max(<values>) | Returns the maximum of a set of string or numeric values. | |
min(<values>) | Returns the minimum of a set of string or numeric values. | |
random() | Returns a pseudo-random integer ranging from zero to 231-1. | |
Text functions | len(<str>) | Returns the count of the number of characters, not bytes, in the string. |
lower(<str>) | Converts the string to lowercase. | |
ltrim(<str>,<trim_chars>) | Removes characters from the left side of a string. | |
replace(<str>,<regex>,<replacement>) | Substitutes the replacement string for every occurrence of the regular expression in the string. | |
rtrim(<str>,<trim_chars>) | Removes the trim characters from the right side of the string. | |
spath(<value>,<path>) | Extracts information from the structured data formats XML and JSON. | |
substr(<str>,<start>,<length>) | Returns a substring of a string, beginning at the start index. The length of the substring specifies the number of character to return. | |
trim(<str>,<trim_chars>) | Trim characters from both sides of a string. | |
upper(<str>) | Returns the string in uppercase. | |
urldecode(<url>) | Replaces URL escaped characters with the original characters. | |
Trigonometry and Hyperbolic functions | acos(X) | Computes the arc cosine of X. |
acosh(X) | Computes the arc hyperbolic cosine of X. | |
asin(X) | Computes the arc sine of X. | |
asinh(X) | Computes the arc hyperbolic sine of X. | |
atan(X) | Computes the arc tangent of X. | |
atan2(X,Y) | Computes the arc tangent of X,Y. | |
atanh(X) | Computes the arc hyperbolic tangent of X. | |
cos(X) | Computes the cosine of an angle of X radians. | |
cosh(X) | Computes the hyperbolic cosine of X radians. | |
hypot(X,Y) | Computes the hypotenuse of a triangle. | |
sin(X) | Computes the sine of X. | |
sinh(X) | Computes the hyperbolic sine of X. | |
tan(X) | Computes the tangent of X. | |
tanh(X) | Computes the hyperbolic tangent of X. |
Alphabetical list of functions
The following table is a quick reference of the supported evaluation functions, organized alphabetically. This table provides a brief description for each function. Use the links in the table to learn more about each function and to see examples.
Supported functions and syntax | Description | Type of function |
---|---|---|
abs(<num>) | Returns the absolute value. | Mathematical functions |
acos(X) | Computes the arc cosine of X. | Trigonometry and Hyperbolic functions |
acosh(X) | Computes the arc hyperbolic cosine of X. | Trigonometry and Hyperbolic functions |
asin(X) | Computes the arc sine of X. | Trigonometry and Hyperbolic functions |
asinh(X) | Computes the arc hyperbolic sine of X. | Trigonometry and Hyperbolic functions |
atan(X) | Computes the arc tangent of X. | Trigonometry and Hyperbolic functions |
atan2(X,Y) | Computes the arc tangent of X,Y. | Trigonometry and Hyperbolic functions |
atanh(X) | Computes the arc hyperbolic tangent of X. | Trigonometry and Hyperbolic functions |
avg(<values>) | Returns the average of numerical values as an integer. | Statistical eval functions |
case(<condition>,<value,...) | Accepts alternating conditions and values. Returns the first value for which the condition evaluates to TRUE. | Comparison and Conditional functions |
cidrmatch(<cidr>,<ip>) | Returns TRUE when an IP address, <ip> , belongs to a particular CIDR subnet, <cidr> .
|
Comparison and Conditional functions |
ceiling(<num>) | Rounds the value up to the next highest integer. | Mathematical functions |
coalesce(<values>) | Takes one or more values and returns the first value that is not NULL. | Comparison and Conditional functions |
commands(<value>) | Returns a multivalued field that contains a list of the commands used in <value>. | Multivalue eval functions |
cos(X) | Computes the cosine of an angle of X radians. | Trigonometry and Hyperbolic functions |
cosh(X) | Computes the hyperbolic cosine of X radians. | Trigonometry and Hyperbolic functions |
exact(<expression>) | Returns the result of a numeric eval calculation with a larger amount of precision in the formatted output. | Mathematical functions |
exp(<num>) | Returns the exponential function eN .
|
Mathematical functions |
false() | Returns FALSE. | Comparison and Conditional functions |
floor(<num>) | Rounds the value down to the next lowest integer. | Mathematical functions |
hypot(X,Y) | Computes the hypotenuse of a triangle. | Trigonometry and Hyperbolic functions |
if(<predicate>,<true_value>,<false_value>) | If the <predicate> expression evaluates to TRUE, returns the <true_value> , otherwise the function returns the <false_value> .
|
Comparison and Conditional functions |
in(<field>,<list>) | Returns TRUE if one of the values in the list matches a value that you specify. | Comparison and Conditional functions |
ipmask(<mask>,<ip>) | The function generates a new masked IP address by applying a mask to an IP address using a bitwise AND operation.
|
Conversion functions |
isbool(<value>) | Returns TRUE if the field value is Boolean. | Informational functions |
isint(<value>) | Returns TRUE if the field value is an integer. | Informational functions |
isnotnull(<value>) | Returns TRUE if the field value is not NULL. | Informational functions |
isnull(<value>) | Returns TRUE if the field value is NULL. | Informational functions |
isnum(<value>) | Returns TRUE if the field value is a number. | Informational functions |
isstr(<value>) | Returns TRUE if the field value is a string. | Informational functions |
json_append(<json>, <path_value_pairs>) | Appends values to the ends of indicated arrays within a JSON document. | JSON functions |
json_array(<values>) | Creates a JSON array using a list of values. | JSON functions |
json_array_to_mv(<json_array>, <boolean>) | Maps the elements of a proper JSON array into a multivalue field. | JSON functions |
json_extend(<json>, <path_value_pairs>) | Flattens arrays into their component values and appends those values to the ends of indicated arrays within a valid JSON document. | JSON functions |
json_extract(<json>, <paths>) | Returns a value from a piece JSON and zero or more paths. The value is returned in either a JSON array, or a Splunk software native type value. | JSON functions |
Returns Splunk software native type values from a piece of JSON by matching literal strings in the event and extracting them as keys. | JSON functions | |
json_keys(<json>) | Returns the keys from the key-value pairs in a JSON object. The keys are returned as a JSON array. | JSON functions |
json_object(<members>) | Creates a new JSON object from members of key-value pairs. | JSON functions |
json_set(<json>, <path_value_pairs>) | Inserts or overwrites values for a JSON node with the values provided and returns an updated JSON object. | JSON functions |
json_set_exact(<json>,<key_value_pairs>) | Uses provided key-value pairs to generate or overwrite a JSON object. | JSON functions |
json_valid(<json>) | Evaluates whether piece of JSON uses valid JSON syntax and returns either TRUE or FALSE. | JSON functions |
len(X) | Returns the count of the number of characters (not bytes) in the string. | Text functions |
like(<str>,<pattern>)) | Returns TRUE only if <str> matches <pattern> .
|
Comparison and Conditional functions |
ln(<num>) | Returns the natural logarithm. | Mathematical functions |
log(<num>,<base>) | Returns the logarithm of <num> using <base> as the base. If <base> is omitted, base 10 is used. | Mathematical functions |
lookup(<lookup_table>, <json_object>, <json_array>) | Performs a CSV lookup. Returns the output field or fields in the form of a JSON object. The |
Comparison and Conditional functions |
len(<str>) | Returns the count of the number of characters, not bytes, in the string. | Text functions |
lower(<str>) | Converts the string to lowercase. | Text functions |
ltrim(<str>,<trim_chars>) | Removes characters from the left side of a string. | Text functions |
match(<str>, <regex>) | Returns TRUE if the regular expression <regex> finds a match against any substring of the string value <str> . Otherwise returns FALSE.
|
Comparison and Conditional functions |
max(<values> | Returns the maximum of a set of string or numeric values. | Statistical eval functions |
md5(<str>) | Computes the md5 hash for the string value. | Cryptographic functions |
min(<values>) | Returns the minimum of a set of string or numeric values. | Statistical eval functions |
mvappend(<values) | Returns a multivalue result based on all of values specified. | Multivalue eval functions |
mvcount(<mv>) | Returns the count of the number of values in the specified field. | Multivalue eval functions |
mvdedup(<mv>) | Removes all of the duplicate values from a multivalue field. | Multivalue eval functions |
mvfilter(<predicate>) | Filters a multivalue field based on an arbitrary Boolean expression. | Multivalue eval functions |
mvfind(<mv>,<regex>) | Finds the index of a value in a multivalue field that matches the regular expression. | Multivalue eval functions |
mvindex(<mv>,<start>,<end>) | Returns a subset of the multivalue field using the start and end index values. | Multivalue eval functions |
mvjoin(<mv>,<delim>) | Takes all of the values in a multivalue field and appends the values together using a delimiter. | Multivalue eval functions |
mvmap(<mv>,<expression>) | This function iterates over the values of a multivalue field, performs an operation using the <expression> on each value, and returns a multivalue field with the list of results. | Multivalue eval functions |
mvrange(<start>,<end>,<step>) | Creates a multivalue field based on a range of specified numbers. | Multivalue eval functions |
mvsort(<mv>) | Returns the values of a multivalue field sorted lexicographically. | Multivalue eval functions |
mvzip(<mv_left>,<mv_right>,<delim>) | Combines the values in two multivalue fields. The delimiter is used to specify a delimiting character to join the two values. | Multivalue eval functions |
mv_to_json_array(<field>, <infer_types>) | Maps the elements of a multivalue field to a JSON array. | JSON functions |
now() | Returns the time that the search was started. | Date and Time functions |
null() | This function takes no arguments and returns NULL. | Comparison and Conditional functions |
nullif(<field1>,<field2>) | Compares the values in two fields and returns NULL if the value in <field1> is equal to the value in <field2> . Otherwise returns the value in <field1> .
|
Comparison and Conditional functions |
pi() | Returns the constant pi to 11 digits of precision. | Mathematical functions |
pow(<num>,<exp>) | Returns <num> to the power of <exp>, <num><exp> .
|
Mathematical functions |
printf(<format>,<arguments>) | Creates a formatted string based on a format description that you provide. | Conversion functions |
random() | Returns a pseudo-random integer ranging from zero to 231-1. | Statistical eval functions |
relative_time(<time>,<specifier>) | Adjusts the time by a relative time specifier. | Date and Time functions |
replace(<str>,<regex>,<replacement>) | Substitutes the replacement string for every occurrence of the regular expression in the string. | Text functions |
round(<num>,<precision>) | Returns <num> rounded to the amount of decimal places specified by <precision>. The default is to round to an integer. | Mathematical functions |
rtrim(<str>,<trim_chars>) | Removes the trim characters from the right side of the string. | Text functions |
searchmatch(<search_str>) | Returns TRUE if the event matches the search string. | Comparison and Conditional functions |
sha1(<str>) | Computes the sha1 hash for the string value. | Cryptographic functions |
sha256(<str>) | Computes the sha256 hash for the string value. | Cryptographic functions |
sha512(<stri>) | Computes the sha512 hash for the string value. | Cryptographic functions |
sigfig(<num>) | Rounds <num> to the appropriate number of significant figures. | Mathematical functions |
sin(X) | Computes the sine of X. | Trigonometry and Hyperbolic functions |
sinh(X) | Computes the hyperbolic sine of X. | Trigonometry and Hyperbolic functions |
spath(<value>,<path>) | Extracts information from the structured data formats XML and JSON. | Text functions |
split(<str>,<delim>) | Splits the string values on the delimiter and returns the string values as a multivalue field. | Multivalue eval functions |
sqrt(<num>) | Returns the square root of the value. | Mathematical functions |
strftime(<time>,<format>) | Takes a UNIX time and renders it into a human readable format. | Date and Time functions |
strptime(<str>,<format>) | Takes a human readable time and renders it into UNIX time. | Date and Time functions |
substr(<str>,<start>,<length>) | Returns a substring of a string, beginning at the start index. The length of the substring specifies the number of character to return. | Text functions |
sum(<num>,...) | Returns the sum of numerical values as an integer. | Mathematical functions |
tan(X) | Computes the tangent of X. | Trigonometry and Hyperbolic functions |
tanh(X) | Computes the hyperbolic tangent of X. | Trigonometry and Hyperbolic functions |
time() | The time that eval function was computed. The time will be different for each event, based on when the event was processed. | Date and Time functions |
tonumber(<str>,<base>) | Converts a string to a number. | Conversion functions |
tostring(<value>,<format>) | Converts the input, such as a number or a Boolean value, to a string. | Conversion functions |
trim(<str>,<trim_chars>) | Trim characters from both sides of a string. | Text functions |
true() | Returns TRUE. | Comparison and Conditional functions |
typeof(<value>) | Returns a string that indicates the field type, such as Number, String, Boolean, and so forth. | Informational functions |
upper(<str>) | Returns the string in uppercase. | Text functions |
urldecode(<url>) | Replaces URL escaped characters with the original characters. | Text functions |
validate(<condition>, <value>,...) | Takes a list of conditions and values and returns the value that corresponds to the condition that evaluates to FALSE. This function defaults to NULL if all conditions evaluate to TRUE. This function is the opposite of the case function.
|
Comparison and Conditional functions |
See also
Topics:
Statistical and charting functions
Commands:
eval
fieldformat
where
SPL data types and clauses | Comparison and Conditional functions |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.0.2305, 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303
Feedback submitted, thanks!