Documentation > Splunk > Search Reference > Functions for eval and where

Search Reference

 


Welcome
Search Overview
Search Commands
Custom Search Commands

Functions for eval and where

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Functions for eval and where

These are functions that you can use with the eval and where commands.

Function Description Example(s)
abs(X) This function takes a number X and returns its absolute value. abs(number)
case(X,"Y",...) This function takes pairs of arguments X and Y. X arguments are Boolean expressions that, when evaluated to TRUE, return the corresponding Y argument. The function defaults to NULL if none are true. case(error == 404, "Not found", error == 500,"Internal Server Error", error == 200, "OK")
cidrmatch("X",Y) This function identifies IP addresses that belong to a particular subnet. The function uses two arguments: the first is the CIDR subnet, which is contained in quotes; the second is the IP address to match, which may be values in a field. cidrmatch("123.132.32.0/25",ip)
coalesce(X,...) This function takes an arbitrary number of arguments and returns the first value that is not null. coalesce(null(), "Returned value", null())
exact(X) This function evaluates an expression X using double precision floating point arithmetic. exact(3.14 * num)
exp(X) This function takes a number X and returns eX. This example returns e3: exp(3)
floor(X) This function returns the floor of a number X. This example returns 1: floor(1.9)
if(X,Y,Z) This function takes three arguments. The first argument X is a Boolean expression. If X evaluates to TRUE, the result is the second argument Y. If X evaluates to FALSE, the result evaluates to the third argument Z. if(error == 200, "OK", "Error")
isbool(X) This function takes one argument X and returns TRUE if X is Boolean. isbool(field)
isint(X) This function takes one argument X and returns TRUE if X is an integer. isint(field)
isnotnull(X) This function takes one argument X and returns TRUE if X is not NULL. This is a useful check for whether or not a field (X) contains a value. isnotnull(field)
isnull(X) This function takes one argument X and returns TRUE if X is NULL. isnull(field)
isnum(X) This function takes one argument X and returns TRUE if X is a number. isnum(field)
isstr() This function takes one argument X and returns TRUE if X is a string. isstr(field)
len(X) This function returns the character length of a string X. len(field)
ln(X) This function takes a number X and returns its natural log. ln(bytes)
log(X,Y) This function takes either one or two numeric arguments and returns the log of the first argument X using the second argument Y as the base. If the second argument Y is omitted, this function evaluates the log of number X with base 10. log(number,2)
lower(X) This function takes one string argument and returns the lowercase version. The upper() function also exists for returning the uppercase version. This example returns the value provided by the field username in lowercase.

lower(username)

ltrim(X,Y) This function takes one or two string arguments X and Y and returns X with the characters in Y trimmed from the left side. If Y is not specified, spaces and tabs are trimmed. This example returns "abcZZ":

ltrim(" ZZZZabcZZ ", " Z")

match(X,Y) This function compares the regex string Y to the value of X and returns a Boolean value; it returns T (true) if X matches the pattern defined by Y. This example returns true IF AND ONLY IF field matches the basic pattern of an IP address. Note that the example uses ^ and $ to perform a full match.

match(field, "^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")

max(X,...) This function takes an arbitrary number of arguments X, that is numbers or strings, and returns the max; strings are greater than numbers. This example returns either "foo" or field, depending on the value of field:

max(1, 3, 6, 7, "f"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")oo", field)

md5(X) This function computes and returns the MD5 hash of a string value X. md5(field)
min(X,...) This function takes an arbitrary number of arguments X, that is numbers or strings, and returns the min; strings are greater than numbers. This example returns 1:

min(1, 3, 6, 7, "f"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")oo", field)

mvcount(X) This function takes an field X and returns the number of values of that field if the field is multivalued, 1 if the field is single valued, and NULL otherwise. mvcount(multifield)
mvfilter(X) This function filters a multi-valued field based on an arbitrary Boolean expression X. The Boolean expression X can reference ONLY ONE field at a time. This example returns all values of the field email that end in .net or .org:

mvfilter(match(email, "\.net$") OR match(email, "\.org$"))

mvindex(X,Y,Z) This function takes two or three arguments, field X and numbers Y and Z, and returns a subset of the multivalued field using the indexes provided.

For mvindex(mvfield, startindex, [endindex]), endindex is inclusive and optional; both startindex and endindex can be negative, where -1 is the last element. If endindex is not specified, it returns just the value at startindex. If the indexes are out of range or invalid, the result is NULL.

Since indexes start at zero, this example returns the third value in "multifield", if it exists:

mvindex(multifield, 2)

now() This function takes no arguments and returns the time that the search was started. The time is represented in Unix time or seconds since epoch.
null() This function takes no arguments and returns NULL. The evaluation engine uses NULL to represent "no value"; setting a field to NULL clears its value.
nullif(X,Y) This function takes two arguments, fields X and Y, and returns the X if the arguments are different. It returns NULL, otherwise. nullif(fieldA,fieldB)
pi() This function takes no arguments and returns the constant pi to 11 digits of precision.
pow(X,Y) This function takes two numeric arguments X and Y and returns XY.
random() This function takes no arguments and returns a pseudo-random number. This example returns a random number between 1 and 20:

... | eval blkah = random() % 20

replace(X,Y,Z) This function returns a string formed by substituting string Z for every occurrence of regex string Y in string X. The third argument Z can also reference groups that are matched in the regex. This example returns date with the month and day numbers switched, so if the input was 1/12/2009 the return value would be 12/1/2009:

replace(date, "^(\d{1,2})/(\d{1,2})/", "\2/\1/")

round(X,Y) This function takes one or two numeric arguments X and Y, returning X rounded to the amount of decimal places specified by Y. The default is to round to an integer. This example returns 4:

round(3.5)

This example returns 2.56:

round(2.555, 2)

rtrim(X,Y) This function takes one or two string arguments X and Y and returns X with the characters in Y trimmed from the right side. If Y is not specified, spaces and tabs are trimmed. This example returns "ZZZZabc":

rtrim(" ZZZZabcZZ ", " Z")

searchmatch(X) This function takes one argument X, which is a search string. The function returns true IF AND ONLY IF the event matches the search string. searchmatch("foo AND bar")
sqrt(X) This function takes one numeric argument X and returns its square root. This example returns 3:

sqrt(9)

substr(X,Y,Z) This function takes either two or three arguments, where X is a string and Y and Z are numeric. It returns a substring of X, starting at the index specified by Y with the number of characters specified by Z. If Z is not given, it returns the rest of the string.

The indexes follow SQLite semantics; they start at 1. Negative indexes can be used to indicate a start from the end of the string.

This example concatenates "str" and "ing" together, returning "string":

substr("string", 1, 3) + substr("string", -3)

tostring(X,Y) This function converts the input value to a string. If the input value is a number, it reformats it as a string. If the input value is a Boolean value, it returns the corresponding string value, "True" or "False".

This function requires at least one argument X; if X is a number, the second argument Y is optional and can either be "hex" or "commas":

  • tostring(X,"hex") converts X to hexadecimal.
  • tostring(X,"commas") formats X with commas and 2 decimal places.
This example returns "True 0xF 12,345.68":

tostring(1==1) + " " + tostring(15, "hex") + " " + tostring(12345.6789, "commas")

trim(X,Y) This function takes one or two string arguments X and Y and returns X with the characters in Y trimmed from both sides. If Y is not specified, spaces and tabs are trimmed. This example returns "abc":

trim(" ZZZZabcZZ ", " Z")

typeof(X) This function takes one argument and returns a string representation of its type. This example returns "NumberStringBoolInvalid":

typeof(12) + typeof("string") + typeof(1==2) + typeof(badfield)

upper(X) This function takes one string argument and returns the uppercase version. The lower() function also exists for returning the lowercase version. This example returns the value provided by the field username in uppercase.

upper(username)

urldecode(X) This function takes one string argument X and returns the URL decoded. This example returns "http://www.splunk.com/download?r=header":

urldecode("http%3A%2F%2Fwww.splunk.com%2Fdownload%3Fr%3Dheader")

validate(X,Y,...) This function takes pairs of arguments, Boolean expressions X and strings Y. The function returns the string Y corresponding to the first expression X that evaluates to False and defaults to NULL if all are True. This example runs a simple check for valid ports:

validate(isint(port), "ERROR: Port is not an integer", port >= 1 AND port <= 65535, "ERROR: Port is out of range")

Retrieved from "http://docs.splunk.com/Documentation/Splunk/4.0/SearchReference/CommonEvalFunctions"

This documentation applies to the following versions of Splunk: 4.0 , 4.0.1 , 4.0.2 , 4.0.3 , 4.0.4 , 4.0.5 , 4.0.6 , 4.0.7 , 4.0.8 , 4.0.9 , 4.0.10 , 4.0.11 View the Article History for its revisions.


You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!