Skip to main content
Splunk® Cloud Services

SPL2 Search Reference

Splunk® Cloud Services
current (latest release)

branch command overview, syntax, and usage

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

The branch command is a terminating command, which is a command that does not return any search results and must be the last command in the search or pipeline. You can nest additional commands for data processing inside the branch command, but you cannot include any commands after the branch command itself.


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 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 command 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 into 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. The filtering, with the where command, uses 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 is 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 $splunk_platform_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 Splunk platform destination.
  • For the second copy, the IP addresses are obscured using the sha256 hashing function, and then the data is sent to an Amazon S3 destination.

The into command must be the last command in each branch. Any other commands that you want to use in the branch for data processing must be specified before this final into command, which sends the results to a destination.

Syntax

The SPL2 branch command supports different syntaxes in different product contexts.

Syntax for searches

In searches, the into command at the end of each branch must specify the name of the dataset that you want to send the results to.

The required syntax is in bold.

branch
[[<additional-SPL2-commands>] | into [mode = (append | replace)] <dataset>],
[[<additional-SPL2-commands>] | into [mode = (append | replace)] <dataset>] ...

Each branch is enclosed in square brackets and separated by commas.

Syntax for pipelines

In pipelines, the into command at the end of each branch must specify the $destination parameter. This parameter refers to the destination dataset specified in the pipeline settings, and determines which destination dataset the results of the branch are sent to.

The required syntax is in bold.

branch
[[<additional-SPL2-commands>] | into <$destination>],
[[<additional-SPL2-commands>] | into <$destination>] ...

Each branch is enclosed in square brackets and separated by commas.

Required arguments

The required arguments are different in each product context.

Searches

dataset
Syntax: <dataset-name>
Description: The name of the dataset to write the search results to. This can be a dataset that you created or a dataset that you are authorized to use.

Pipelines

dataset
Syntax: <$destination>
Description: This argument must be set to the $destination parameter. The $destination parameter refers to the destination dataset specified in the pipeline settings. See the Pipeline examples on the branch command examples topic.

Optional arguments

The required arguments are different in each product context.

Searches

additional-SPL2-commands
Syntax: <additional-SPL2-commands>
Description: One or more SPL2 commands to process the data before it is written to the <dataset>. See the Specifying filters examples on the branch command examples topic.
mode
Syntax: mode=( append | replace )
Description: Specifies whether to append results to or replace results in the specified dataset. The replace setting only applies to lookup datasets.
Default: append

Pipelines

additional-SPL2-commands
Syntax: <additional-SPL2-commands>
Description: One or more SPL2 commands to process the data before it is routed to the <$destination>. See the Pipeline examples on the branch command examples topic.

Usage

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

Filtering in branches

You can use the first command in a branch to specify conditions or filters for that branch, for example:

| from people | branch [where (age < 13 ) | stats count() BY firstname | into child_names], [where gender = "M" | stats count() BY firstname | into male_names], [where gender = "F" | stats count() BY firstname | into female_names], [stats count() BY firstname | into names]

This search loads all of the people into memory and then sends those events down 4 branches.

  • The first 3 branches use the where command to filter the events for people in particular groups (children, men and women) and then calculates the count using the stats command.
  • The last branch does not specify a filter before the stats command.

Multiple branch commands

You can't specify multiple parallel branch commands in search or pipeline.

Valid usage

This example is valid because there is only one branch command:

| from people | branch [where (age < 13 ) | stats count() BY firstname | into child_names], [where gender = "M" | stats count() BY firstname | into male_names], [where gender = "F" | stats count() BY firstname | into female_names], [stats count() BY firstname | into names]

Invalid usage

This example is invalid because you can't specify multiple branch commands at the same level:

| from people | branch [where (age < 13 ) | stats count() BY firstname | into child_names] | branch [where gender = "M" | stats count() BY firstname | into male_names], [where gender = "F" | stats count() BY firstname | into female_names], [stats count() BY firstname | into names]

Nested branch commands

You can specify nested branch commands.

Search example

Here is a search example of nested branch commands:

| from cities | branch [ where population < 10000 | stats count() BY name | into villages], [ where population > 1000000 | stats count() by name | into cities], [ where population >= 10000 AND population <= 1000000 | branch [ where region="northeast" | stats count() by name | into ne_towns], [ where region="south" | stats count() by name | into s_towns], [ where region="midwest" | stats count() by name | into mw_towns], [ where region="west" | stats count() by name | into w_towns] ]

Pipeline example

Here is a pipeline example with nested branch commands: 

$pipeline = | from $source 
| flatten _raw
| rename name as NAME
| branch [
    | where country = "USA" 
    | where state = "New York" 
    | into $destination1
], [
    | where country = "Japan" 
    | where state = "Kanto" 
    | into $destination2
], [
    | where country = "Netherlands"  
    | branch [
        | where state = "North Holland" 
        | into $destination3
    ], [
        | where NAME  = "Rotterdam" 
        | where state = "South Holland" 
        | into $destination4
    ]
], [
    | where country = "UK" 
    | into $destination5
]

See also

branch command
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
Last modified on 31 March, 2025
bin command examples   branch command examples

This documentation applies to the following versions of Splunk® Cloud Services: current

Acrobat logo Download manual
Acrobat logo Download this page

Please expect delayed responses to documentation feedback while the team migrates content to a new system. We value your input and thank you for your patience as we work to provide you with an improved content experience!

Was this topic useful?







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