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 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.

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.

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.

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

Required arguments

The required arguments are different in each product context.

Searches

Pipelines

Optional arguments

The required arguments are different in each product context.

Searches

Pipelines

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
]