Extend and branch SPL2 search statements

A powerful feature of modules is the ability to create and extend or branch a base search. A base search applies filters to events to curate the events into a useful set of search results. From there you can extend or branch the base search by adding more filters or by applying commands to summarize or transform the search results.

This image shows two diagrams. The first diagram shows a base search with two consecutive child searches. The second diagram shows a base search and two parallel branch searches.

You can combine extending and branching either from the same base search, or from a child or branch search in your module.

Extending a base search

Extending searches is a great way to use successive searches to build or troubleshoot complex searches.

The following set of searches illustrate how to use a base search and to extend search statements. Each child search uses the results of the previous search as its dataset. Line comments are used to describe the purpose of each search. 

// RETURNS SUCCESSFUL EVENTS
$base_search = from sample_events where status=200 

// RETURNS CATEGORIES THAT START WITH "S" FROM THE WWW4 HOST
$child1 = from $base_search  
where categoryId LIKE("S%") AND host="www4" 
select _time, action, productId, categoryId

// FILTERS OUT EVENTS WITH NULL VALUES IN ACTION
$child2 = from $child1 where action!="NULL" 

// RETURNS A COUNT OF EVENTS BY CATEGORY ID
$child3 = from $child2 
| stats count() by categoryId

Branching a base search

You can branch searches from a base search to generate unrelated search results. Unlike extended searches, branch searches are independent from one another.

The following set of searches illustrate how to use a base search and branch searches. Each branch search uses the base search as its dataset. Line comments are used to describe the purpose of each search. 

// RETURNS PURCHASE EVENTS
$base_search = from sample_events 
where action="purchase" 

// RETURNS A COUNT OF THE EVENTS GROUPED BY HOST
$branch1 = from $base_search  
| stats count() BY host

// RETURNS A SUM OF BYTES BY HOST, RENAMES THE CALCULATED FIELD
$branch2 = from $base_search
| stats sum(bytes) AS 'Sum of bytes' BY host

// CALCULATES KBs ROUNDED TO 3 DECIMALS, RETURNS SPECIFIC FIELDS
$branch3 = from $base_search
| eval kbytes = round(bytes / 1024, 3)
| select _time, bytes, kbytes

// GROUPS EVENTS, RETURNS SPECIFIC FIELDS WITH A CALCULATED FIELD
$branch4 = from $base_search
group by productId 
select productId, count(action) AS 'Count of actions'

Some of these examples show fields names that contain spaces. Field names that contain spaces or special characters, other than the underscore ( _ ), must be enclosed in single quotation marks.