Modules and SPL2 statements

A module is like a file that consists of one or more related SPL2 statements. SPL2 statements are searches and other types of data-related code.

Modules are useful for grouping a set of related searches, functions, and data type definitions. Here are some examples for using modules:

• To contain a series of search statements, where each statement uses the output from the previous statement
• To define a function in a function statement and then use that function in a search statement
• To process the same data in multiple different ways to avoid running a common base search again
• To contain a set of searches and custom functions designed for one or more teams to share

Modules always live inside a namespace. Namespaces are like folders in a file system. Modules are files inside the folders.

You can think of modules in this way:

• A module is a story.
• A statement is a sentence in the story.
• A command is a word in a sentence in the story.

The following diagram shows a personal namespace for teamA:

Inside the namespace, teamA has an index dataset and a module which is named moduleA. Inside the module there are three search statements and a custom function statement called isError.

Here's an example of a module in the Search and Dashboard Experience in Splunk Cloud Platform:

In the diagram, notice that the search results from the searches are located inside the namespace and not the module. That's because the search results are themselves a dataset, and datasets are stored at the namespace level not at the module level.

Modules contain only SPL2-related items. All non-SPL2 items, such as indexes, search results, lookups, and built-in datasets reside in namespaces. See Built-in datasets.

SPL2 statements

SPL2 statements are data-related code that you can create inside a module. You can create several different types of SPL2 statements:

• Search statements which are a special type of assignment statement
• Custom function statements
• Custom data type statements
• Export statements
• Import statements

Search statements

Search statements consist of a name, the equal sign, and the SPL2 search.

For example:

$search1=FROM main WHERE latest=-4h@h GROUP BY host

The name is formatted as a variable, which begins with a dollar sign ( $ ) and can be composed of uppercase or lowercase letters, numbers, and the underscore ( _ ) character.

A search statement is a special type of assignment statement, where the expression part of the assignment statement is the SPL2 search.

When you create an SPL2 search statement, the statement can only refer to the following items:

• Items defined in the module, such as custom function statements or custom data type statements
• Items that reside in the namespace, such as indexes, lookups, or search results
• Items that are imported into the module

Using view datasets

When you run a search statement that returns a dataset, the dataset is referred to as a view dataset. You can use the dataset generated by one search as the source dataset for subsequent searches.

For example, the name of this search statement is $countByHost:

$countByHost = FROM main | stats count() BY host

To use the view dataset generated by $countByHost in subsequent searches, specify the name of the search statement anywhere you specify a dataset. The view dataset $countByHost is used in both of the following examples:

$top50hosts = FROM $countByHost | sort - count | head 10

$mostRareHosts = FROM $countByHost WHERE count < 5 SELECT host

Custom function statements

There are two types of custom functions, custom eval functions and custom command functions. Custom functions are user-defined functions that you declare in an SPL2 module. Custom functions are similar to macros.

Use custom eval functions to extend SPL2. For example, this custom function returns error codes that are greater than or equal to 400:

function isError($code : number) : boolean {
  return $code >= 400 
}

For more information and examples, see Custom eval functions.

Custom command functions are functions that perform like a command. There are generating and non-generating custom command functions. Here's an example of a non-generating custom command function that returns the most common values for a field in a dataset:

function top($source, $field, $limit: int) {
    return | FROM $source 
        | stats count() by $field 
        | sort -count
        | head $limit
}

For more information and examples, see Custom command functions.

Custom data type statements

Use custom data types to specify a set of complex characteristics that define the shape of your data. A wide range of custom data types are supported. Constrained types apply a constraint, in the form of a predicate expression, on an existing built-in or custom data type. In this example, a where clause with an IN function is the constraint:

type http_error=int where $value in([403, 404, 408])

For more information and examples, see Custom data types.

Export and import statements

To share SPL2 statements in your module with other users, you must publish the module and designate which items you want to export. Other users can import the exported items into their own modules.

For example, the following sample module called qtr1_activity shows an import statement for a dataset, several search statements, a function statement, and three export statements:

qtr1_activity

import sample_events from /splunk_sample_data/sample_datasets

$hostwww4 = from sample_events where status=200 AND host="www4"

$cat_id = from $hostwww4 where categoryId IN("SIMULATION","STRATEGY")

$bytes = from sample_events | stats sum(bytes) AS 'Sum of bytes' BY host

$purchases = from sample_events where status=200 AND action="purchase" 

function isError($code : number) : boolean {
  return $code >= 400 
}

export $cat_id
export $purchases
export isError

The following example shows a module called yearly_activity, that contains shows an import statement for a dataset, import statements for two view datasets, and an import statement for a function:

yearly_activity

import sample_events from /splunk_sample_data/sample_datasets
import cat_id
import purchases
import isError

For more information, see:

• Exporting module items using SPL2
• Importing items using SPL2
• Specifying import paths

Using multiple modules

You can create multiple modules under a namespace. The following diagram shows a namespace for a security group. There is a module for each of the three teams in this group.

In addition to creating multiple modules under a single namespace, you can also create multiple namespaces.

Modules and datasets

From your modules, you can use the datasets in your namespace, such as indexes and lookups, as well as search result datasets.

When you run a search in a module, the search checks to ensure that the dataset referenced in the search is accessible from that module.

To learn more about sharing searches, indexes, and other items, see Importing items using SPL2.

See also

Related information

Datasets

Extend and branch search statements