if command: Overview, syntax, and usage

The SPL2 if command splits a search or pipeline into multiple processing paths and conditionally routes events to specific paths based on the filtering conditions that you specify. Use the if command to process specific subsets of events differently.

How the SPL2 if command works

The if command contains one or more paths, where each path consists of the following:

  • A predicate expression that filters the data

  • One or more additional SPL2 commands that transform and work with the data

The if command evaluates each event against the predicate expressions in the order that the expressions are specified. The command then passes the event to the first path where the predicate evaluates to true.

For example, the following if command contains 3 paths, and is followed by a where command:

CODE 
...  
| if (level="FATAL") [eval priority=1] 
	elseif (level="ERROR") [eval priority=2] 
	else [eval priority=3] 
| where confidential=false

This if command does the following:

  • Passes events that contain the field-value pair level=FATAL to the first path, which adds the priority=1 field-value pair to the events.

  • Passes events that contain the field-value pair level=ERROR to the second path, which adds the priority=2 field-value pair to the events.

  • Passes events that don't meet either of the aforementioned conditions to the third path, which adds the priority=3 field-value pair to the events.

    Note: This third path specifies default behavior for all events that do not meet the previous filter conditions, so it does not include a predicate expression.

The events from those paths are passed to the next command in the SPL2 statement after the if command. In this case, the events go to a where command that filters for a confidential flag.

Syntax

The required syntax is in bold.

if (predicate-expression) [additional-SPL2-commands]

[elseif (predicate-expression) [additional-SPL2-commands]]

[elseif (predicate-expression) [additional-SPL2-commands]] ...

[else [additional-SPL2-commands]]

Each predicate-expression argument must be enclosed in parentheses ( ), and each additional-SPL2-commands argument must be enclosed in square brackets ( [ ] ).

Required arguments

predicate_expression

Syntax: (predicate-expression)

Description: A predicate expression that, when evaluated, returns either true or false. This predicate expression must be enclosed in parentheses.

additional-SPL2-commands

Syntax: [additional-SPL2-commands]

Description: One or more SPL2 commands for transforming the events for which the preceding predicate expression evaluates to true. This set of commands must be enclosed in square brackets ( [ ] ).

Usage

The following sections contain information to help you understand and use the SPL2 if command.

Specifying multiple processing paths

When configuring the if command, you must specify at least one processing path. This processing path consists of the command name, a predicate expression, and one or more SPL2 commands. For example, the following if command updates events that have price values under 25 with the price_tier=low field-value pair before sending all of the events to the next command in the search or pipeline:

CODE 
...
| if (price < 25) [eval price_tier="low"] 
| where on_sale=true

You can then specify additional processing paths using elseif expressions. Each elseif expression contains a predicate expression followed by one or more SPL2 commands. You can add as many elseif expressions to the if command as necessary. For example, the following if command conditionally assigns different price_tier values to events based on the value in the price field before filtering for events where the value of the on_sale field is true.

CODE 
...
| if (price < 25) [eval price_tier="low"] 
	elseif (price BETWEEN 25 AND 50) [eval price_tier="mid"] 
	elseif (price > 50) [eval price_tier="high"] 
| where on_sale=true

You can optionally include an else expression as the last expression in the if command to specify a default processing path for all events that do not meet the earlier conditions. For example, the following if command starts by conditionally assigning different price_tier values to events based on the value in the price field. Then, for any events that do not contain a price field, the if command updates the on_sale field to a value of false.

CODE 
...  
| if (price < 25) [eval price_tier="low"] 
	elseif (price BETWEEN 25 AND 50) [eval price_tier="mid"] 
	elseif (price > 50) [eval price_tier="high"]
	else [eval on_sale=false]
| where on_sale=true

Use narrow filters first

The if command filters events by evaluating them against the predicate expressions in the specified order, and passes events to the first processing path where the predicate expression evaluates to true. To ensure that the if command passes events to the most relevant path, specify the paths in order from the most narrow filtering condition to the most broad filtering condition.

For example, assume that the following logs are flowing through your search or pipeline:

level message priority
FATAL Unexpected system shutdown 1
ERROR User login failure 2
INFO Connection established 3
DEBUG Concurrent server connections: 10 3

Assume also that the search or pipeline contains the following if command:

CODE 
... 
| if (priority IN(2,3)) [eval diagnostic=false]
	elseif (level="DEBUG") [eval diagnostic=true]
	else [eval diagnostic=false, label="Attention needed"]

This if command routes the logs to different indexes as follows:

  • Logs where the value of the priority field is either 2 or 3 are updated with the diagnostic=false field-value pair.

  • Logs where the value of the level field is DEBUG are updated with the diagnostic=true field-value pair.

  • All logs where the priority value is not 2 or 3 and the level value is not DEBUG are updated with the eval diagnostic=false and label="Attention needed" field-value pairs.

Because the processing path for events with priority=3 is specified before the path for events with level=DEBUG, the log that has both the level=DEBUG and priority=3 field-value pairs gets tagged with diagnostic=false. As a result, this log gets omitted when customer support teams search for data with the diagnostic=true field-value pair, potentially compromising incident investigation and troubleshooting.