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, custom functions, and custom data types. 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 custom function in a function statement and then use that function in a search statement.
• To process the same data in multiple different ways by including a common base search in subsequent searches.
• 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.

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.

Import and export statements

Items that you want to use from another module or from a namespace must be imported into your module.

For example, to use a dataset, such as an index or a lookup, you must include an import statement in your module. The import statement brings that dataset into scope.

When you add an import statement to a module, you are not physically importing the item into the module. Instead, you are adding a pointer to the item that resides in another module or namespace. When you refer to the item in a search or function, the item is retrieved from the source.

The path you specify to import an item depends on whether the item is outside the namespace or inside the namespace.

To import an item, you must know the namespace for that item.

To share items from one module to another, you must export the items that you want to share.

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 main from ../../../../indexes

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

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

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

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

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

export main
export $cat_id
export $purchases
export isError

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

yearly_activity

import main from ../../../../indexes
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

SPL2 Views

Extend and branch search statements

Understanding SPL2 namespaces