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 team_a:

This image shows a namespace for team_a. The namespace contains an index, a module, and several search results. The module contains several different types of SPL statements.

Inside the namespace, team_a has an index dataset and a module which is named module_a. Inside the module there are 3 search statements and a custom function statement called is_error.

Here's an example of a module in the SPL2 Editor:

This image shows a module for teamA. The module contains in import statement, several search statements, and a function statement.

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.

Note: 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, 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 one search as the dataset in other searches

When you run a search, the results returned are a dataset. You can use the dataset generated by one search as the source dataset for other searches:

To use the results from one search in a subsequent search in the same module, you must branch the search. For more information and examples, see Branch SPL2 searches.
To use the results from a search in another module, you must create an SPL2 view. An SPL2 view is a named SPL2 search that has been exported from a module. For more information and examples, see SPL2 views.

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.

Custom eval functions

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

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

For more information and examples, see Custom eval functions.

Custom command functions

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 for your module.

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.

Note: 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 = search index=main status=200 host="www3"

$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 is_error($code : number) : boolean {
  return $code >= 400 
}

export main
export $cat_id
export $purchases
export is_error

The following example shows a module called yearly_activity, that contains an import statement for an index, import statements for 2 views, and an import statement for a function:

yearly_activity

import main from ~indexes
import cat_id
import purchases
import is_error

For more information, see:

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.

This image shows a namespace for a security group. Each team has its own module: incidents team, response team, and audit team. Each module contains several SPL statements.

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.