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.
TO DO - UPDATE THE PLACE YOU CAN USE PREDICATES IN SPL
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:
TO DO - UPDATE FOR SPL |
... 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: |
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 the string "error" and 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 thewhere
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 thecustomers
dataset - The
status
field for the customer number in theorders
dataset contains the value "pending" - For each product number in the
products
dataset there is a matching a product number in theorders
dataset - The
availability
field for the product number in theproducts
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
Types of expressions | Boolean expressions |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.3.2408
Feedback submitted, thanks!