Splunk Enterprise version 8.1 will no longer be supported as of April 19, 2023. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise.
For documentation on the most recent version, go to the latest release.
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 which contains the names of your servers. You want to append the literal string server at the end of the name. You would specify this: 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(X,"Y",...) | Accepts alternating conditions and values. Returns the first value for which the condition evaluates to TRUE. |
| cidrmatch("X",Y) | Returns TRUE or FALSE based on whether an IP address matches a CIDR notation. | |
| coalesce(X,...) | This function takes an arbitrary number of arguments and returns the first value that is not NULL. | |
| false() | Returns FALSE. | |
| if(X,Y,Z) | If the condition X evaluates to TRUE, returns Y, otherwise returns Z. | |
| in(FIELD, VALUE-LIST) | The function returns TRUE if one of the values in the list matches a value in the field you specify. | |
| like(TEXT, PATTERN) | Returns TRUE if TEXT matches PATTERN. | |
| lookup(<lookup_table>, <json_object>, <json_array>) | This function performs a CSV lookup. It returns the output field or fields in the form of a JSON object. | |
| match(SUBJECT, "REGEX") | Returns TRUE or FALSE based on whether REGEX matches SUBJECT | |
| null() | This function takes no arguments and returns NULL. | |
| nullif(X,Y) | This function is used to compare fields. The function takes two arguments, X and Y, and returns NULL if X = Y. Otherwise it returns X. | |
| searchmatch(X) | Use this function to return TRUE if the search string (X) matches the event. | |
| true() | Returns TRUE. | |
| validate(X,Y,...) | Use this function to return the string Y corresponding to the first expression X that evaluates to FALSE. This function is the opposite of the case function.
| |
| Conversion functions | printf("format",arguments) | Creates a formatted string based on a format description that you provide. |
| tonumber(NUMSTR,BASE) | Converts a string to a number. | |
| tostring(X,Y) | Converts the input, such as a number or a Boolean value, to a string. | |
| Cryptographic functions | md5(X) | Computes the md5 hash for the value X. |
| sha1(X) | Computes the sha1 hash for the value X. | |
| sha256(X) | Computes the sha256 hash for the value X. | |
| sha512(X) | Computes the sha512 hash for the value X. | |
| Date and Time functions | now() | Returns the time that the search was started. |
| relative_time(X,Y) | Adjusts the time by a relative time specifier. | |
| strftime(X,Y) | Takes a UNIX time and renders it into a human readable format. | |
| strptime(X,Y) | 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(X) | Returns TRUE if the field value is Boolean. |
| isint(X) | Returns TRUE if the field value is an integer. | |
| isnotnull(X) | Returns TRUE if the field value is not NULL. | |
| isnull(X) | Returns TRUE if the field value is NULL. | |
| isnum(X) | Returns TRUE if the field value is a number. | |
| isstr(X) | Returns TRUE if the field value is a string. | |
| typeof(X) | 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_array(<values>) | Creates a JSON array using a list of values. | |
| 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_keys(<json>) | Returns the keys from the key-value pairs in a JSON object. The keys are returned 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_valid(<json>) | Evaluates whether piece of JSON uses valid JSON syntax and returns either TRUE or FALSE. | |
| Mathematical functions | abs(X) | Returns the absolute value. |
| ceiling(X) | Rounds the value up to the next highest integer. | |
| exact(X) | Returns the result of a numeric eval calculation with a larger amount of precision in the formatted output. | |
| exp(X) | Returns the exponential function eX.
| |
| floor(X) | Rounds the value down to the next lowest integer. | |
| ln(X) | Returns the natural logarithm. | |
| log(X,Y) | Returns the logarithm of X using Y as the base. If Y is omitted, base 10 is used. | |
| pi() | Returns the constant pi to 11 digits of precision. | |
| pow(X,Y) | Returns X to the power of Y, XY.
| |
| round(X,Y) | Returns X rounded to the amount of decimal places specified by Y. The default is to round to an integer. | |
| sigfig(X) | Rounds X to the appropriate number of significant figures. | |
| sqrt(X) | Returns the square root of the value. | |
| sum(X,...) | Returns the sum of numerical values as an integer. | |
| Multivalue eval functions | commands(X) | Returns a multivalued field that contains a list of the commands used in X. |
| mvappend(X,...) | Returns a multivalue result based on all of values specified. | |
| mvcount(MVFIELD) | Returns the count of the number of values in the specified field. | |
| mvdedup(X) | Removes all of the duplicate values from a multivalue field. | |
| mvfilter(X) | Filters a multivalue field based on an arbitrary Boolean expression X. | |
| mvfind(MVFIELD,"REGEX") | Finds the index of a value in a multivalue field that matches the REGEX. | |
| mvindex(MVFIELD,STARTINDEX,ENDINDEX) | Returns a set of values from a multivalue field described by STARTINDEX and ENDINDEX. | |
| mvjoin(MVFIELD,STR) | Takes all of the values in a multivalue field and appends them together delimited by STR. | |
| mvmap(X,Y) | This function iterates over the values of a multi-value field (X), performs an operation (Y) on each value, and returns a multi-value field with the list of results. | |
| mvrange(X,Y,Z) | Creates a multivalue field with a range of numbers between X and Y, incrementing by Z. | |
| mvsort(X) | Returns the values of a multivalue field sorted lexicographically. | |
| mvzip(X,Y,"Z") | Takes two multivalue fields, X and Y, and combines them by stitching together the first value of X with the first value of field Y, then the second with the second, and so on. | |
| split(X,"Y") | Returns a mv field splitting X by the delimited character Y. | |
| Statistical eval functions | avg(X,...) | Returns the average of numerical values as an integer. |
| max(X,...) | Returns the maximum of the string or numeric values. | |
| min(X,...) | Returns the minimum of the string or numeric values. | |
| random() | Returns a pseudo-random integer ranging from zero to 231-1. | |
| Text functions | len(X) | Returns the count of the number of characters (not bytes) in the string. |
| lower(X) | Converts the string to lowercase. | |
| ltrim(X,Y) | Trims the characters represented in Y from the left side of the string. | |
| replace(X,Y,Z) | Returns a string formed by substituting string Z for every occurrence of regex string Y in string X. | |
| rtrim(X,Y) | Returns X with the characters in Y trimmed from the right side. | |
| spath(X,Y) | Extracts a value from a structured data type (XML or JSON) in X based on a location path in Y. | |
| substr(X,Y,Z) | Returns a substring from X based on the starting position Y and the length Z. | |
| trim(X,Y) | Trims the characters represented in Y from both sides of the string X. | |
| upper(X) | Returns the string in uppercase. | |
| urldecode(X) | 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(X) | Returns the absolute value. | Mathematical functions |
| avg(X,...) | Returns the average of numerical values as an integer. | Statistical eval 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 |
| case(X,"Y",...) | Accepts alternating conditions and values. Returns the first value for which the condition evaluates to TRUE. | Comparison and Conditional functions |
| cidrmatch("X",Y) | Returns TRUE or FALSE based on whether an IP address matches a CIDR notation. | Comparison and Conditional functions |
| ceiling(X) | Rounds the value up to the next highest integer. | Mathematical functions |
| coalesce(X,...) | This function takes an arbitrary number of arguments and returns the first value that is not NULL. | Comparison and Conditional functions |
| commands(X) | Returns a multivalued field that contains a list of the commands used in X. | 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(X) | Returns the result of a numeric eval calculation with a larger amount of precision in the formatted output. | Mathematical functions |
| exp(X) | Returns the exponential function eX.
|
Mathematical functions |
| false() | Returns FALSE. | Comparison and Conditional functions |
| floor(X) | 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(X,Y,Z) | If the condition X evaluates to TRUE, returns Y, otherwise returns Z. | Comparison and Conditional functions |
| in(FIELD, VALUE-LIST) | The function returns TRUE if one of the values in the list matches a value in the field you specify. | Comparison and Conditional functions |
| isbool(X) | Returns TRUE if the field value is Boolean. | Informational functions |
| isint(X) | Returns TRUE if the field value is an integer. | Informational functions |
| isnotnull(X) | Returns TRUE if the field value is not NULL. | Informational functions |
| isnull(X) | Returns TRUE if the field value is NULL. | Informational functions |
| isnum(X) | Returns TRUE if the field value is a number. | Informational functions |
| isstr(X) | Returns TRUE if the field value is a string. | Informational functions |
| json_object(<members>) | Creates a new JSON object from members of key-value pairs. | JSON functions |
| json_array(<values>) | Creates a JSON array using a list of values. | JSON functions |
| 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 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_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_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(TEXT, PATTERN) | Returns TRUE if TEXT matches PATTERN. | Comparison and Conditional functions |
| log(X,Y) | Returns the logarithm of X using Y as the base. If Y is omitted, base 10 is used. | Mathematical functions |
| lookup(<lookup_table>, <json_object>, <json_array>) | This function performs a CSV lookup. It returns the output field or fields in the form of a JSON object. | Comparison and Conditional functions |
| ln(X) | Returns the natural logarithm. | Mathematical functions |
| lower(X) | Converts the string to lowercase. | Text functions |
| ltrim(X,Y) | Trims the characters represented in Y from the left side of the string. | Text functions |
| match(SUBJECT, "REGEX") | Returns TRUE or FALSE based on whether REGEX matches SUBJECT. | Comparison and Conditional functions |
| max(X,...) | Returns the maximum of the string or numeric values. | Statistical eval functions |
| md5(X) | Computes the md5 hash for the value X. | Cryptographic functions |
| min(X,...) | Returns the minimum of the string or numeric values. | Statistical eval functions |
| mvappend(X,...) | Returns a multivalue result based on all of values specified. | Multivalue eval functions |
| mvcount(MVFIELD) | Returns the count of the number of values in the specified field. | Multivalue eval functions |
| mvdedup(X) | Removes all of the duplicate values from a multivalue field. | Multivalue eval functions |
| mvfilter(X) | Filters a multivalue field based on an arbitrary Boolean expression X. | Multivalue eval functions |
| mvfind(MVFIELD,"REGEX") | Finds the index of a value in a multivalue field that matches the REGEX. | Multivalue eval functions |
| mvindex(MVFIELD,STARTINDEX,ENDINDEX) | Returns a set of values from a multivalue field described by STARTINDEX and ENDINDEX. | Multivalue eval functions |
| mvjoin(MVFIELD,STR) | Takes all of the values in a multivalue field and appends them together delimited by STR. | Multivalue eval functions |
| mvmap(X,Y) | This function iterates over the values of a multi-value field (X), performs an operation (Y) on each value, and returns a multi-value field with the list of results. | Multivalue eval functions |
| mvrange(X,Y,Z) | Creates a multivalue field with a range of numbers between X and Y, incrementing by Z. | Multivalue eval functions |
| mvsort(X) | Returns the values of a multivalue field sorted lexicographically. | Multivalue eval functions |
| mvzip(X,Y,"Z") | Takes two multivalue fields, X and Y, and combines them by stitching together the first value of X with the first value of field Y, then the second with the second, and so on. | Multivalue eval 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(X,Y) | This function is used to compare fields. The function takes two arguments, X and Y, and returns NULL if X = Y. Otherwise it returns X. | Comparison and Conditional functions |
| pi() | Returns the constant pi to 11 digits of precision. | Mathematical functions |
| pow(X,Y) | Returns X to the power of Y, XY.
|
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(X,Y) | Adjusts the time by a relative time specifier. | Date and Time functions |
| replace(X,Y,Z) | Returns a string formed by substituting string Z for every occurrence of regex string Y in string X. | Text functions |
| round(X,Y) | Returns X rounded to the amount of decimal places specified by Y. The default is to round to an integer. | Mathematical functions |
| rtrim(X,Y) | Returns X with the characters in Y trimmed from the right side. | Text functions |
| searchmatch(X) | Use this function to return TRUE if the search string (X) matches the event. | Comparison and Conditional functions |
| sha1(X) | Computes the sha1 hash for the value X. | Cryptographic functions |
| sha256(X) | Computes the sha256 hash for the value X. | Cryptographic functions |
| sha512(X) | Computes the sha512 hash for the value X. | Cryptographic functions |
| sigfig(X) | Rounds X 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(X,Y) | Extracts a value from a structured data type (XML or JSON) in X based on a location path in Y. | Text functions |
| split(X,"Y") | Returns a mv field splitting X by the delimited character Y. | Multivalue eval functions |
| sqrt(X) | Returns the square root of the value. | Mathematical functions |
| strftime(X,Y) | Takes a UNIX time and renders it into a human readable format. | Date and Time functions |
| strptime(X,Y) | Takes a human readable time and renders it into UNIX time. | Date and Time functions |
| substr(X,Y,Z) | Returns a substring from X based on the starting position Y and the length Z. | Text functions |
| sum(X,...) | 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(NUMSTR,BASE) | Converts a string to a number. | Conversion functions |
| tostring(X,Y) | Converts the input, such as a number or a Boolean value, to a string. | Conversion functions |
| trim(X,Y) | Trims the characters represented in Y from both sides of the string X. | Text functions |
| true() | Returns TRUE. | Comparison and Conditional functions |
| typeof(X) | Returns a string that indicates the field type, such as Number, String, Boolean, and so forth. | Informational functions |
| upper(X) | Returns the string in uppercase. | Text functions |
| urldecode(X) | Replaces URL escaped characters with the original characters. | Text functions |
| validate(X,Y,...) | Use this function to return the string Y corresponding to the first expression X that evaluates to FALSE. This function is the opposite of the case function.
|
Comparison and Conditional functions |
See also
Topics:
Statistical and charting functions
Commands:
eval
fieldformat
where
Last modified on 26 October, 2021
| SPL data types and clauses | Comparison and Conditional functions |
This documentation applies to the following versions of Splunk® Enterprise: 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14
Download manual
Feedback submitted, thanks!