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
• Alphabetical list of 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_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.
	mv_to_json_array(<field>, <Boolean>)	Maps the elements of a multivalue field to a JSON array.
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.
	json_array_to_mv(<json_array>, <Boolean>)	Maps the elements of a proper JSON array into a multivalue field.
	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.
	mv_to_json_array(<field>, <Boolean>)	Maps the elements of a multivalue field to a JSON array.
	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
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(X,...)	Returns the average of numerical values as an integer.	Statistical eval 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_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
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 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(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
mv_to_json_array(<field>, <Boolean>)	Maps the elements of a multivalue field to a JSON array.	JSON 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