Splunk® Cloud Services

SPL2 Search Manual

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Predicate expressions

A predicate is an expression that consists of operators or keywords that specify a relationship between two expressions. A predicate expression, when evaluated, returns either TRUE or FALSE.

Think of a predicate expression as an equation. The result of that equation is a Boolean.

You can use predicate expressions in the WHERE and HAVING clauses in the from command, and in the where command. See the from command overview and the where command overview in the SPL2 Search Reference.

Filtering with predicates

Predicates are often used to filter data or specify a condition to reduce the number of search results.

The following predicate expression uses the in function to filter the results in the status field.

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

Types of predicate operators

The following table describes the types of predicate operators that you can use in expressions:

Predicate operator type Description Examples
Relational operators Relational operators use symbols to check for equality, inequality, or relative order between two expressions. Examples of relational operators are equal to ( = ) and is greater than ( > ). 
clientip = "192.0.2.0"

count > 15
Logical operators An operator that performs a comparison between two expression. The supported logical operators are: AND, OR, NOT, and XOR. 
A=1 AND ( B=2 OR C=3 )
error NOT (403 OR 404)
Conditional and pattern-matching operators A predicate expression that uses a keyword operator to test for a condition or match a pattern. Conditional and pattern matching operators include: 
... HAVING ipaddress BETWEEN "192.0.2.0" AND "192.0.2.255"

| FROM main AS m1 WHERE EXISTS (SELECT 1 FROM main WHERE host=m1.host AND host=www1) ... 
| search status IN (401, 403)
...WHERE host IS NULL
...WHERE ipaddress LIKE "198.%"
Boolean functions A function that returns a Boolean. Evaluation functions, such as in, isnum, like, and match are examples of functions that return TRUE. See Quick Reference for SPL2 eval functions in the SPL2 Search Reference. 
... | where status in("400", "401", "403", "404")

isnotnull(client_ip)

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

Relational operators

The relational operators are symbols that compare one expression with another expression. Relational operators evaluate whether the expressions are equal to, not equal to, greater than or less than on another,

The supported operators are:

  • equals ( = ) or ( == )
  • does not equal ( != )
  • is greater than ( > )
  • is greater than or equal to ( >= )
  • is less than ( < )
  • is less than or equal to ( <= )

Logical operators

The logical operators compare one expression with another expression.

Syntax

The syntax for using logical operators is:

<expression> <logical-operator> <expression>

The supported operators are describe in the following table:

Operator Description
AND Both expressions must evaluate to TRUE.

The AND operator is always implied between terms, that is: web error is the same as web AND error. So unless you want to include it for clarity reasons, you should not need to specify the AND operator.

OR One of the expressions must evaluate to TRUE.
NOT The expressions cannot be equal to one another.

The NOT operator only applies to the term immediately following NOT. To apply to multiple terms, you must enclose the terms in parenthesis.

XOR An exclusive OR. One and only one of the expressions must evaluate to TRUE.

Inclusion is generally better than exclusion. Searching for "access denied" will yield faster results than NOT "access granted".

Order of evaluation

The order in which the Splunk software evaluates predicate expressions depends on whether you are using the expression with the WHERE or HAVING clause in the from command, the where command, or the search command.

The following table describes the order in which the logical expressions are evaluated.

Order Search command From or where commands
1 Expressions inside parentheses Expressions inside parentheses
2 NOT operators NOT operators
3 OR operators AND operators
4 AND operators OR operators

Examples

The following examples show how Splunk software processes Boolean expressions.

Consider the following search:

A=1 AND B=2 OR C=3

This is the same as specifying A=1 B=2 OR C=3

When you specify values without parenthesis, this search is processed as:

A=1 AND ( B=2 OR C=3 )

To force the search to process the values in a specific order, use parenthesis:

(A=1 AND B=2 ) OR C=3


Here is another example:

error NOT 403 OR 404

Without parenthesis, this search is processed as:

  • Search for any event that contains the string "error" and does not contain the keyword 403
  • Search for any event that contains both. the string "error" and keyword 404

You can use parentheses to group Boolean expressions. For example:

error NOT (403 OR 404)


You can use time modifiers in the expressions with logical operators: 

...WHERE earliest=-5m@m AND latest=@m

For more information about using time modifiers, see Time modifiers in the SPL2 Search Manual.

BETWEEN operator

Use the BETWEEN operator to compare the values in an <expression> with the values in a range of values between a <low_value> and a <high-value>.

You can specify the BETWEEN and AND operators in uppercase or lowercase.

Syntax

The syntax for the BETWEEN operator is:

<expression> BETWEEN <low-value> AND <high-value>

You can also use the NOT operator with the BETWEEN operator. The syntax is:

<expression> NOT BETWEEN <low-value> AND <high-value>

Examples

quake_magnitude BETWEEN 4 AND 8
client_ip between "192.0.2.0" and "192.0.2.24" 
threshold NOT BETWEEN -1.2 AND 3.5
... HAVING ipaddress BETWEEN "192.0.2.0" AND "192.0.2.255"

EXISTS operator

Use the EXISTS operator to test if an event in the main search dataset correlates with at least one event in the subsearch dataset. The EXISTS operator returns TRUE if a match is found. The main search returns the events for every correlation match.

The dataset that you specify in the main search must be aliased using the AS keyword. Otherwise the EXISTS operator returns an error.

Syntax

The syntax for the EXISTS operator is:

EXISTS (<subsearch>)

Syntax requirements

There are several syntax requirements when you use the EXISTS operator:

  • The <subsearch> must include a WHERE clause with an expression that correlates an event in the main search dataset with an event in the subsearch dataset.
  • The EXISTS operator only supports the equal ( = ) operator in the correlation expression. Other logical operators are not supported. Use NOT EXISTS for inequality expressions.
  • The LIMIT and OFFSET clauses are not supported in the subsearch.
  • In the WHERE clause of the subsearch, you can only use functions on the field in the subsearch dataset.
  • You can use the EXISTS operator in the WHERE or HAVING clause in the from command. If your search includes both a WHERE and a HAVING clause, the EXISTS expression must be in the HAVING clause. The EXISTS operator is not supported with the where command.

Examples

Specifying a single EXISTS operator

In this example, the orders dataset is renamed o1 and referenced in the subsearch. For each product number in the products dataset that matches a product number in the orders dataset, and the product availability is "in stock", the EXISTS operator returns TRUE.

FROM orders AS o1 WHERE EXISTS ( SELECT prodno FROM products WHERE prodno = o1.prodno AND availability="in stock") GROUP BY span (_time, 3h) SELECT custno, orderno, status

The results are organized by the _time field in increments of 3 hours. The customer number, order number, and status fields from the orders dataset are returned.

Specifying the NOT operator with the EXISTS operator

You can use the NOT operator to specify conditions that you don't want to match. You cannot use the != relational operator inside the subsearch.

In this example, the orders dataset is renamed o1 and referenced in the subsearch. For each product number in the products dataset that does not match a product number in the orders dataset, and the product availability is anything other than "in stock", the NOT EXISTS operator returns TRUE.

FROM orders AS o1 WHERE NOT EXISTS ( SELECT prodno FROM products WHERE prodno = o1.prodno AND availability="in stock") GROUP BY span (_time, 3h) SELECT custno, orderno, status

The results are organized by the _time field in increments of 3 hours. The customer number, order number, and status fields from the orders dataset are returned.

Specifying multiple sequential EXISTS operators

You can use multiple EXISTS operators in a search. In this example, there are two sequential EXISTS operators to check for different conditions

In this example, the customer dataset is renamed c1 and referenced in the subsearch. If all of the following conditions are met, the EXISTS operator returns TRUE:

  • For each customer number in the orders dataset there is a matching a customer number in the customers dataset
  • The status field for the customer number in the orders dataset contains the value "pending"
  • For each product number in the products dataset there is a matching a product number in the orders dataset
  • The availability field for the product number in the products dataset contains the value "back ordered".

FROM customers AS c1 WHERE EXISTS ( SELECT orderno FROM orders WHERE custno = c1.custno AND status="pending") AND EXISTS ( SELECT prodno FROM products WHERE prodno = o1.prodno AND availability="back ordered") SELECT customer_name, city, state, phone ORDER BY customer_name ASC

The customer name, city , state, and phone number are returned. The results are sorted by the customer_name field in alphabetical order.

IN operator

The IN operator matches the values in a field to any of the items in the <expression-list>. The items in the <expression-list> must be a comma-separated list.

The in function is similar to the IN operator. See Comparison and conditional functions in the SPL2 Search Reference.

Syntax

The syntax for the IN operator is:

<field-expression> IN (<expression-list>)

You can also use the NOT operator with the IN operator. The syntax is:

<field-expression> NOT IN (<expression-list> )

Examples

code IN(10, 29)
status IN("400", "401", "403", "404")
status NOT IN("200", "202", "204")
| search status IN (401, 403)


IS NULL operator

Use the IS NULL operator to test if a field value is null.

Syntax

The syntax for the IS NULL operator is:

<expression> IS NULL

You can also use the NOT operator with the IS NULL operator to test if the field value is not null. The syntax is:

<expression> IS NOT NULL

Examples

...WHERE client_ip IS NULL
... WHERE client_ip IS NOT NULL


LIKE operator

Use the LIKE operator to match a pattern. You use the percent ( % ) symbol as a wildcard anywhere in the <pattern-expression>.

The LIKE operator is similar to the like function. See Comparison and conditional functions in the SPL2 Search Reference.

Syntax

The syntax for the LIKE operator is:

<field-expression> LIKE <pattern-expression>

You can also use the NOT operator with the LIKE operator. The syntax is:

<field-expression> NOT LIKE <pattern-expression>

Examples

name LIKE "Pete%"
surname LIKE "%son"
client_ip NOT LIKE "192.0.2.%"
...WHERE ipaddress LIKE "198.%.100.0"

See also

Related information
Types of expressions
Last modified on 20 February, 2024
PREVIOUS
Types of expressions 		  NEXT
Search literals in expressions

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