Splunk® Cloud Services

SPL2 Search Reference

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Comparison and Conditional functions

The following list contains the functions that you can use to compare values or specify conditional statements.

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 evaluation functions.

case(<condition>, <value>, ...)

This function takes pairs of <condition> and <value> arguments and returns the first value for which the condition evaluates to TRUE.

Usage

The <condition> arguments are Boolean expressions that are evaluated from first to last. When the first <condition> expression is encountered that evaluates to TRUE, the corresponding <value> argument is returned. The function defaults to NULL if none of the <condition> arguments are true.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the pairs of arguments in an array, enclosing the values in square brackets. The syntax for named arguments is case(conditions: [<condition>, <value>,...]. For example: 

... case(conditions: [status == 200, "OK", status ==404, "Not found"])

Basic example

The following example returns descriptions for the corresponding HTTP status code.

|from my_dataset where sourcetype="access_*" | eval description=case(status == 200, "OK", status ==404, "Not found", status == 500, "Internal Server Error") | fields status, description

The results look something like this:

status description
200 OK
200 OK
408
200 OK
404 Not found
200 OK
406
500 Internal Server Error
200 OK

Specifying a default value

In the above example, the description column is empty for status=406 and status=408.

To display a default value when the status does not match one of the values specified, use the literal true. For example:

|from my_dataset where sourcetype="access_*" | eval description=case(status == 200, "OK", status ==404, "Not found", status == 500, "Internal Server Error", true, "Other") | table status description

The word Other displays in the search results for status=406 and status=408.

Extended example

This example shows you how to use the case function in two different ways, to create categories and to create a custom sort order.

This example uses earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that contains magnitude (mag), coordinates (latitude, longitude), region (place), and so forth, for each earthquake recorded.

You want classify earthquakes based on depth. Shallow-focus earthquakes occur at depths less than 70 km. Mid-focus earthquakes occur at depths between 70 and 300 km. Deep-focus earthquakes occur at depths greater than 300 km. We'll use Low, Mid, and Deep for the category names.

| from my_dataset where source="all_month.csv" | eval Description=case(depth<=70, "Low", depth>70 AND depth<=300, "Mid", depth>300, "Deep") | stats count min(mag) max(mag) by Description

The eval command is used to create a field called Description, which takes the value of "Low", "Mid", or "Deep" based on the Depth of the earthquake. The case() function is used to specify which ranges of the depth fits each description. For example, if the depth is less than 70 km, the earthquake is characterized as a shallow-focus quake; and the resulting Description is Low.

The search also pipes the results of the eval command into the stats command to count the number of earthquakes and display the minimum and maximum magnitudes for each Description.

The results look something like this:

Description count min(Mag) max(Mag)
Deep 35 4.1 6.7
Low 6236 -0.60 7.70
Mid 635 0.8 6.3

You can sort the results in the Description column by clicking the sort icon in Splunk Web. However in this example the order would be alphabetical returning results in Deep, Low, Mid or Mid, Low, Deep order.

You can also use the case function to sort the results in a custom order, such as Low, Mid, Deep. You create the custom sort order by giving the values a numerical ranking and then sorting based on that ranking.

from my_dataset where source="all_month.csv" | eval Description=case(depth<=70, "Low", depth>70 AND depth<=300, "Mid", depth>300, "Deep") | stats count min(mag) max(mag) by Description | eval sort_field=case(Description="Low", 1, Description="Mid", 2, Description="Deep",3) | sort sort_field

The results look something like this:

Description count min(Mag) max(Mag)
Low 6236 -0.60 7.70
Mid 635 0.8 6.3
Deep 35 4.1 6.7

cidrmatch(<cidr>, <ip>)

Returns TRUE or FALSE based on whether an IP address matches a CIDR notation.

This function returns TRUE when an IP address, <ip>, belongs to a particular CIDR subnet, <cidr>. This function is compatible with IPv6.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Both <cidr> and <ip> are string arguments. If you specify a literal string value, instead of a field name, that value must be enclosed in double quotation marks.

To use named arguments, you must specify the argument names before the argument values. For example: 

... cidrmatch(cidr:"192.0.2.0/24", ip:ipAddress)

Basic examples

The following example uses the cidrmatch and if functions to set a field, isLocal, to "local" if the field ipAddress matches the subnet. If the ipAddress field does not match the subnet, the isLocal field is set to "not local".

... | eval isLocal=if(cidrmatch("192.0.2.0/24",ipAddress), "local", "not local")


The following example uses the cidrmatch function as a filter to remove events where the values in the mycidr field do not match the IP address.

... | where NOT cidrmatch(mycidr, "203.0.113.255")

coalesce(<values>)

This function takes one or more values and returns the first value that is not NULL.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the values in an array, enclosing the values in square brackets. The syntax for named arguments is coalesce(values: [<value1>, <value2>,...]. For example: 

... coalesce(values: [clientip, ipaddress, "203.0.113.255"])

Basic examples

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 the clientip field or ipaddress field, depending on which field is not NULL (does not exist in that event). If both the clientip and ipaddress field exist in the event, this function returns the value in first argument, the clientip field.

... | eval ip=coalesce(clientip, ipaddress)

If neither field exists in the events, you can specify a default value:

... | eval ip=coalesce(clientip, ipaddress, "203.0.113.255")

if(<predicate>, <true_value>, <false_value>)

If the <predicate> expression evaluates to TRUE, returns the <true_value>, otherwise the function returns the <false_value.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

The if function is frequently used in combination with other functions.

To use named arguments, you must specify the argument names before the argument values. For example: 

... if(predicate:error == 200, true_value:"OK", false_value:"Error")

Basic examples

The following example looks at the values of the error field. If error=200, the function returns err=OK. Otherwise the function returns err=Error.

... | eval err=if(error == 200, "OK", "Error")


The following example uses the cidrmatch and if functions to set a field, isLocal, to "local" if the field ip matches the subnet. If the ip field does not match the subnet, the isLocal field is set to "not local".

... | eval isLocal=if(cidrmatch("123.132.32.0/25",ip), "local", "not local")

in(<value>, <list>)

The function returns TRUE if one of the values in the list matches a value that you specify.

This function takes a list of comma-separated values.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

The following syntax is supported:

...WHERE in(<value>, [<list>]) or ...| where in(<value>, [<list>])
...WHERE <value> in([<list>]) or ...| where <value> in([<list>])
...| eval new_field=if(in(<value>, [<list>]), "true_value", "false_value")

The eval command cannot accept a Boolean value. You must specify the in() function inside the if() function, which can accept a Boolean value as input.

The string values must be enclosed in quotation marks. You cannot specify wildcard characters in the list of values to specify a group of similar values, such as HTTP error codes or CIDR IP address ranges. Use the IN operator instead.

The IN predicate operator is similar to the in() function. You can use the IN operator with the search command, as well as the same commands and clauses where you can use the in() function. See Predicate expressions in the SPL2 Search Manual.

To use named arguments, you must specify the argument names before the argument values. Specify the list in an array, enclosing the list in square brackets. The syntax for named arguments is ...in(value:<value>, list:[<value1>, <value2>,...]). For example:

... in(value:status, list:["400", "401", "403", "404"])

Basic examples

Specifying a list of values

The following example uses the where command to return in=TRUE if one of the values in the status field matches one of the values in the list.

... | where status in("400", "401", "403", "404")

Specifying a list of fields

The following example uses the where command to return in=TRUE if the value 203.0.113.255 appears in either the ipaddress or clientip fields.

... | where "203.0.113.255" in(ipaddress, clientip)

Using the in function inside another function

The following example uses the in() function as the first parameter for the if() function. The evaluation expression returns TRUE if the value in the status field matches one of the values in the list.

... | eval error=if(in(status, "error", "failure", "severe"),"true","false")

Extended example

The following example combines the in function with the if function to evaluate the status field. The value of true is placed in the new field error if the status field contains one of the values 404, 500, or 503. Then a count is performed of the values in the error field.

... | eval error=if(in(status, "404","500","503"),"true","false") | stats count() by error

For additional in function examples, see the blog Smooth operator | Searching for multiple field values.

like(<str>, <pattern>)

This function returns TRUE if the string value matches the pattern.

This function returns TRUE if, and only if, str matches pattern. The pattern language supports an exact text match, as well as percent ( % ) characters for wildcards, and underscore ( _ ) characters for a single character match.

You can use the percent ( % ) wildcard anywhere in the <pattern>.

Usage

The <str> can be a field name or a string value. The <pattern> must be a string expression enclosed in double quotation marks. . You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

The following syntax is supported:

command syntax
WHERE clause ...WHERE like(<str>, <pattern>)

...WHERE <str> LIKE <pattern>

eval command ...|eval new_field=if(like(<str>, <pattern>)
where command ...| where like(<str>, <pattern>)

...| where <str> LIKE <pattern>

The eval command cannot accept a Boolean value. You must specify the like() function inside the if() function, which can accept a Boolean value as input.

To use named arguments, you must specify the argument names before the argument values. For example: 

... like(str:ipaddress, pattern:"198.%")

The LIKE predicate operator is similar to the like() function. You can use the LIKE operator with the same commands and clauses where you can use the like() function. See Predicate expressions in the SPL2 Search Manual.

Basic examples

The following example returns like=TRUE if the field value starts with foo:

... | eval is_a_foo=if(like(field, "foo%"), "yes a foo", "not a foo")


The following example uses the where command to return like=TRUE if the ipaddress field starts with the value 198.. The percent ( % ) symbol is a wildcard with the like function:

... | where like(ipaddress, "198.%")

match(<str>, <regex>)

This function returns TRUE if the regular expression <regex> finds a match against any substring of the string value <str>. Otherwise returns FALSE.

Usage

The match function is regex based. For example use the backslash ( \ ) character to escape a special character, such as a quotation mark. Use the pipe ( | ) character to specify an OR condition.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the argument names before the argument values. For example: 

... match(str: ipAddress, regex: "^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")

Basic examples

The following example returns TRUE if, and only if, field matches the basic pattern of an IP address. This examples uses the caret ( ^ ) character and the dollar ( $ ) symbol to perform a full match.

... | eval n=if(match(field, "^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"), 1, 0)


The following example uses the match function in an <eval-expression>. The <str> is a calculated field called test. The <regex> is the string yes.

... | eval matches = if(match(test,"yes"), 1, 0)

If the value is stored with quotation marks, you must use the backslash ( \ ) character to escape the embedded quotation marks. For example:

| from [{ }] | eval test="\"yes\"" | eval matches = if(match(test, "\"yes\""), 1, 0)

This example creates a single event using the from command and an empty dataset literal string value [{ }], which returns the _time field.

nullif(<value1>, <value2>)

This function compares two values and returns NULL if <value1> = <value2>. Otherwise it returns <value1>.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the argument names before the argument values. For example: 

... nullif(value1:ipAddress, value2:clientip)

Basic examples

The following example returns NULL if fieldA=fieldB. Otherwise the function returns fieldA.

... | eval n=nullif(fieldA,fieldB)

searchmatch(<search_str>)

This function returns TRUE if the event matches the search string.

Usage

To use the searchmatch function with the eval command, you must use the searchmatch function inside the if function.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the argument name before the argument value. For example: 

... if(searchmatch(search_str:<event>) ...)

Example

The following example creates an event the contains a timestamp and two fields x and y.

| from [{ }] | eval x="hi" | eval y="goodbye"

The results look like this:

_time x y
9/2/2020 1:29:58.000 PM hi goodbye

Add the searchmatch function to determine if the <search_str> matches the event:

| from [{ }] | eval x="hi" | eval y="goodbye" | eval test=if(searchmatch("x=hi y=*"), "yes", "no") | fields test x y


The results look like this:

test x y
yes hi goodbye

validate(<condition>, <value>, ...)

This function 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.

Usage

The <condition> arguments must be expressions.

The <value> arguments must be strings.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

To use named arguments, you must specify the pairs of arguments in an array, enclosing the values in square brackets. The syntax for named arguments is validate(conditions: [<condition>, <value>,...]. For example: 

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

Example

The following example runs a simple check for valid ports.

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

See also

Functions
SPL2 eval functions Quick Reference
Overview of SPL2 eval functions
Last modified on 08 September, 2021
PREVIOUS
SPL2 eval functions Quick Reference
  NEXT
Conversion functions

This documentation applies to the following versions of Splunk® Cloud Services: current


Was this documentation topic helpful?

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

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters