branch command overview

The SPL2 branch command processes one set of events or search results, in parallel, simultaneous searches. Each search branch must end with the into command.

Syntax

The required syntax is in bold.

branch

[<SPL-literal> | into <dataset>],

[<SPL-literal> | into <dataset>] ...

How the SPL2 branch command works

Using the SPL2 branch command, you can take one set of data and apply different filters simultaneously against that data. The simultaneous filters are referred to as branches. The results of the filters are placed into separate datasets, using the into command.

The branch command works differently in different product contexts:

• In seaches
• In pipelines

In searches

Consider the following search. This search reads the events in the main index dataset into memory one time. The events are then processed in two branches using subsearches to determine the most popular hosts and sources.

| from main | branch [stats count() BY host | where count > 50 select host | into p_hosts], [stats count() BY source | where count > 100 select source | into p_sources]

• The first branch uses the stats command to count the events by host and returns only those hosts with a count above the threshold of 50. Using the into command, the results are appended to the p_hosts dataset.
• The second branch is similar. The stats command is used to count the events by source and returns only those sources with a count above the threshold of 100. Using the into command, the results are appended to the p_sources dataset.

The branch command does not return any results to the search endpoint. You must send the search results to a dataset using the into command. The into must be the last command in each branch.

The data that you search can be events or search results. The previous example used events from the main index. The following search uses the results returned from the beginning of a search and then processes that data in 3 branches.

| from my_dataset where earliest=-5m@m AND latest=@m | branch [stats avg(cpu_usage) BY host | where avg(cpu_usage) > 2000000 select host | into cpu_hosts], [stats count() BY host | where count > 50 select host | into p_hosts], [stats count() BY source | where count > 100 select source | into p_sources ]

In this example, the average and count aggregations must be calculated first, because the filtering, with the where command, use those aggregations. In other situations, you might want to filter before the aggregations. See the branch command examples.

By default, the into command appends search results to an existing dataset that you have write access to. The mode argument is only valid when the dataset is a lookup kind of dataset. See Dataset kinds in the SPL2 Search Manual.

In pipelines

The branch command can be used to make separate copies of the incoming data and send the data into different destination datasets, such as an index or an Amazon S3 bucket.

Consider the following pipeline:

$pipeline = | from $source
| branch
[ | eval index="buttercup" | into $cisco_syslog_destination],
[ | eval ip_address = sha256(ip_address) | into $aws_s3_destination]

This example uses the branch command to make 2 complete copies of the incoming data and send the data to different destinations.

• For the first copy, the data is sent to an existing index named buttercup in a cisco_syslog destination.
• For the second copy, the IP addresses are obscured by using the hashing function, sha256, and then the data is sent to an Amazon S3 destination.

See also

branch command

branch command syntax details

branch command usage

branch command examples

Other commands

into command overview

where command overview

Pipelines

Edge Processor pipeline syntax in the Use Edge Processors manual

Ingest Processor pipeline syntax in the Use Ingest Processors manual