Functions for eval and where
Functions for eval and where
These are functions that you can use with the eval and where commands and as part of eval expressions.
| Function | Description | Example(s) |
|---|---|---|
abs(X)
| This function takes a number X and returns its absolute value. | This example returns the absnum, whose values are the absolute values of the numeric field 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. | This example returns descriptions for the corresponding http status code:
|
ceil(X), ceiling(X)
| This function returns the ceiling of a number X. | This example returns n=2:
|
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. | This example returns a field, addy, whose values are the IP addresses in the field ip that match the subnet:
|
coalesce(X,...)
| This function takes an arbitrary number of arguments and returns the first value that is not null. | Let's say you have a set of events where the IP address is extracted to either clientip or ipaddress. This example defines a new field called ip, that takes the value of either clientip or ipaddress, depending on which is not NULL (exists in that event):
|
commands(X)
| This function takes a search string, or field that contains a search string, X and returns a multivalued field containing a list of the commands used in X. (This is generally not recommended for use except for analysis of audit.log events.) | ... | eval x=commands("search foo | stats count | sort count")
returns a multivalue field x, that contains 'search', 'stats', and 'sort'. |
exact(X)
| This function evaluates an expression X using double precision floating point arithmetic. | ... | eval n=exact(3.14 * num)
|
exp(X)
| This function takes a number X and returns eX. | This example returns y=e3:
|
floor(X)
| This function returns the floor of a number X. | This example returns 1:
|
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. Optionally, if X evaluates to FALSE, the result evaluates to the third argument Z. | This example looks at the values of error and returns err=OK if error=200, otherwise returns err=Error:
|
isbool(X)
| This function takes one argument X and returns TRUE if X is Boolean. | ... | eval n=if(isbool(field),"yes","no")
or
|
isint(X)
| This function takes one argument X and returns TRUE if X is an integer. | ... | eval n=isint(field)
or
|
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. | ... | eval n=if(isnotnull(field),"yes","no")
or
|
isnull(X)
| This function takes one argument X and returns TRUE if X is NULL. | ... | eval n=if(isnull(field),"yes","no")
or
|
isnum(X)
| This function takes one argument X and returns TRUE if X is a number. | ... | eval n=if(isnum(field),"yes","no")
or
|
isstr()
| This function takes one argument X and returns TRUE if X is a string. | ... | eval n=if(isstr(field),"yes","no")
or
|
len(X)
| This function returns the character length of a string X. | ... | eval n=len(field)
|
like(X,"Y")
| This function takes two arguments, a field X and a quoted string Y, and returns TRUE if and only if the first argument is like the SQLite pattern in Y. | This example returns islike=TRUE if the field value starts with foo:
or
|
ln(X)
| This function takes a number X and returns its natural log. | This example returns the natural log of the values of 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. | ... | eval num=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.
|
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 x="abcZZ":
|
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.
|
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:
|
md5(X)
| This function computes and returns the MD5 hash of a string value X. | ... | eval n=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:
|
mvappend(X,"Y",Z)
| This function takes three arguments, fields X and Z and a quoted string Y, and returns a multivalued result. The value of Y and the values of the field Z are appended to the values of field X. The fields X and Z can be either multi or single valued fields. | |
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. | ... | eval n=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.
Note:This function will return NULL values of the field | This example returns all values of the field email that end in .net or .org:
|
mvfind(X,"Y")
| Appears in 4.2.2. This function tries to find a value in multivalued field X that matches the regular expression Y. If a match exists, the index of the first matching value is returned (beginning with zero). If no values match, NULL is returned. | ... | eval n=mvfind(mymvfield, "err\d+")
|
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 | Since indexes start at zero, this example returns the third value in "multifield", if it exists:
|
mvjoin(X,Y)
| This function takes two arguments, multi-valued field X and string delimiter Y, and joins the individual values of X using Y. | This example joins together the individual values of "foo" using a semicolon as the delimiter:
|
mvrange(X,Y,Z)
| This function creates a multivalue field for a range of numbers. It takes up to three arguments: a starting number X, an ending number Y (exclusive), and an optional step increment Z. If the increment is a timespan (such as '7'd), the starting and ending numvers are treated as epoch times. | This example returns a multivalue field with the values 1, 3, 5, 7, 9.
|
mvzip(X,Y)
| This function 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, etc. Similar to Python's zip command. | ... | eval n=server=mvzip(hosts,ports)
|
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. | ... | eval n=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 ranging from zero to 231-1, for example: 0…2147483647 | |
relative_time(X,Y)
| This function takes an epochtime time, X, as the first argument and a relative time specifier, Y, as the second argument and returns the epochtime value of Y applied to X. | ... | eval n=relative_time(now(), "-1d@d")
|
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:
|
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 n=4:
This example returns n=2.56:
|
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 n="ZZZZabc":
|
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. | ... | eval n=searchmatch("foo AND bar")
|
sigfig(X)
| This function takes one argument X, a number, and rounds that number to the appropriate number of significant figures. | 1.00*1111 = 1111, but
returns n=1110. |
spath(X,Y)
| This function takes two arguments: an input source field X and an spath expression Y, that is the XML or JSON formatted location path to the value that you want to extract from X. If Y is a literal string, it needs quotes, spath(X,"Y"). If Y is a field name (with values that are the location paths), it doesn't need quotes. This may result in a multivalued field. Read more about the spath search command.
| This example returns the values of locDesc elements:
This example returns the hashtags from a twitter event:
|
split(X,"Y")
| This function takes two arguments, field X and delimiting character Y. It splits the value(s) of X on the delimiter Y and returns X as a multi-valued field. | ... | eval n=split(foo, ";")
|
sqrt(X)
| This function takes one numeric argument X and returns its square root. | This example returns 3:
|
strftime(X,Y)
| This function takes an epochtime value, X, as the first argument and renders it as a string using the format specified by Y. For a list and descriptions of format options, refer to the topic "Common time format variables". | This example returns the hour and minute from the _time field:
|
strptime(X,Y)
| This function takes a time represented by a string, X, and parses it using the format specified by Y. For a list and descriptions of format options, refer to the topic "Common time format variables". | This example returns the hour and minute from the timeStr field:
|
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":
|
time()
| This function returns the wall-clock time with microsecond resolution. The value of time() will be different for each event based on when that event was processed by the eval command.
| |
tonumber("X",Y)
| This function converts the input string X to a number, where Y is optional and used to define the base of the number to convert to. Y can be 2..36, and defaults to 10. If it cannot parse the input to a number, the function returns NULL. | This example returns "164":
|
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 be
| This example returns "True 0xF 12,345.68":
This example returns |
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":
|
typeof(X)
| This function takes one argument and returns a string representation of its type. | This example returns "NumberStringBoolInvalid":
|
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.
|
urldecode(X)
| This function takes one URL string argument X and returns the unescaped or decoded URL string. | This example returns "http://www.splunk.com/download?r=header":
|
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:
|
This documentation applies to the following versions of Splunk: 5.0 , 5.0.1 , 5.0.2 , 5.0.3 View the Article History for its revisions.