Splunk® Enterprise

Search Reference

Download manual as PDF

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 Evaluation functions.

case(X,"Y",...)

Description

This function takes pairs of arguments X and Y. The X arguments are Boolean expressions that are evaluated from first to last. When the first X expression is encountered that evaluates to TRUE, the corresponding Y argument is returned. The function defaults to NULL if none are true.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

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

... | eval description=case(error ==404, "Not found", error == 500, "Internal Server Error", error == 200, "OK")


cidrmatch("X",Y)

Description

Use this function to determine if an IP address belongs to a particular subnet. This function returns true, when IP address Y belongs to a particular subnet X. Both X and Y are string arguments. X is the CIDR subnet. Y is the IP address to match with the subnet. This function is compatible with IPv6.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

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")


The following example uses cidrmatch as a filter to remove events that do not match the ip address:

... | where cidrmatch("123.132.32.0/25", ip)

coalesce(X,...)

Description

This function takes an arbitrary number of arguments and returns the first value that is not null.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

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 exists in that event). If both the clientip and ipaddress field exist in the event, this function returns the first argument, the clientip field.

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


false()

Description

This function enables you to specify a conditional that is obviously false, for example 1==0. You do not specify a field with this function.

Usage

This function is often used as an argument with other functions.

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

if(X,Y,Z)

Description

This function takes three arguments. The first argument X must be 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.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

The if function is frequently used with other functions. See Basic examples.

Basic examples

The following example looks at the values of the field error. 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)

Description

This function takes a list of comma-separated values. The function returns TRUE if one of the values in the list matches a value in the field you specify.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions with other commands.

There is also an IN operator that is similar to the in(VALUE-LIST) function that you can use with the search and tstats commands.

The following syntax is supported:

...| where in(field,"value1","value2", ...)
...| where field in("value1","value2", ...)
...| eval new_field=in(field,"value1","value2", ...)

The values must be enclosed in quotation marks. You cannot specify wildcard characters with the values.


Basic examples

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")


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", "fail*", "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


like(TEXT, PATTERN)

Description

This function takes two arguments, a string to match TEXT and a string expression to match PATTERN. It returns TRUE if, and only if, TEXT 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.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

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 field value starts with foo:

... | where like(field, "foo%")


match(SUBJECT, "REGEX")

Description

This function compares the regex string REGEX to the value of SUBJECT and returns a Boolean value. It returns TRUE if the REGEX can find a match against any substring of SUBJECT.

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, fieldformat, and where commands, and as part of eval expressions.

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 SUBJECT is a calculated field called test. The "REGEX" is the string yes.

This example uses the match function in an <eval-expression>. The SUBJECT 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:

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

null()

Description

This function takes no arguments and returns NULL. The evaluation engine uses NULL to represent "no value". Setting a field value to NULL clears the field value.

Usage

NULL values are field values that are missing in a some results but present in another results.

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

Suppose you want to calculate the average of the values in a field, but several of the values are zero. If the zeros are placeholders for no value, the zeros will interfere with creating an accurate average. You can use the null function to remove the zeros.

See also

  • You can use the fillnull command to replace NULL values with a specified value.
  • You can use the nullif(X,Y) function to compare two fields and return NULL if X = Y.


nullif(X,Y)

Description

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.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

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

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


searchmatch(X)

Description

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.

Usage

The searchmatch 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, fieldformat, and where commands, and as part of eval expressions.

Basic examples

The following example uses a pipe ( | ) character to specify an OR condition in the searchmatch function.

... searchmatch("Authentication failure|Failed User")


true()

Description

This function enables you to specify a condition that is obviously true, for example 1==1. You do not specify a field with this function.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

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")


validate(X,Y,...)

Description

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.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

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")

PREVIOUS
Evaluation functions
  NEXT
Conversion functions

This documentation applies to the following versions of Splunk® Enterprise: 6.6.0, 6.6.1, 6.6.2


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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