Importing module items and datasets using SPL2

You can import items such as views, custom functions, and custom data types into your modules if those items have been exported from their source module. See Exporting module items using SPL2.

You can also import datasets, such as indexes and lookups, into a module from their source.

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

The syntax to import items into a module depends on how many items you want to import:

Import requirements

To import an item, you must have three things:

  • Access to the source module where the item was exported from, or access to the dataset.
  • The name of the item.
  • The name of the source module or dataset.

Import statement syntax

The import statement syntax is: 

import <item_name> from <source_name>

Specifying the path

Depending on the source location of the item you want to import, you might need to specify a path in your import statement. You can specify either the fully qualified path to the item, or use the relative path that is based on your destination module.

See Specifying import paths.

Import a single item

As shown in the following image, the search $threats is exported from the module current_incidents. The search is exported as a view, with the name threats.


This image shows a namespace that includes two modules. The "current_incidents" module has a search called $threats. The "$threats" search has been exported as a view called "threats". The "threats" view is imported into the "recent_incidents" module.

To import the threats view into the recent_incidents module, you use this import statement: 

import threats from current_incidents

Since the source module and the destination module are in the same namespace, there is no need to specify a path to the source module. You only need to specify the name of the source module.

Import multiple items

You can import multiple items with one import statement, as long as all of those items come from the same source module or namespace.

When you specify multiple items, you must enclose the list of items in curly brackets { }.

The import statement syntax is: 

import {<item_name>, <item_name>, ...} from <source_name>

The following image shows a namespace that includes two modules, current_incidents and resolved_threats.

The current_incidents module contains three search statements: $threats, $top10threats, and $threats_by_type. The module also contains a function statement called dedup_threats.

The $threats and $threats_by_type search statements have been exported as views. The dedup_threats function statement has also been exported. The threats view, the threats_by_type view, and the dedup_threats function are imported into the resolved_threats module.

This image shows a namespace that includes two modules. In the first module, two of the three search statements and a function have been exported. The exported items have been imported into the other module, as described by the text before the image.

The import statement used to import the two views and the function that were exported from the current_incidents module is: 

import {threats, threats_by_type, dedup_threats} from current_incidents

Alternatively, you can issue separate import statements for each item. When you place the import statements on separate lines, you do not need to enclose the import statements in curly brackets { }. For example: 

import threats from current_incidents
import threats_by_type from current_incidents
import dedup_threats from current_incidents

Importing items from different modules

To import items from different modules, you must use separate import statements. In the following example, a view called metrics is imported from the biz_set_1 module and a custom function called count_sigfig_threats is imported from the biz_set_2 module: 

import metrics from biz_set_1   // A view
import count_sigfig_threats from biz_set_2  // A custom function

Import all items

You can use a single statement to import all of the items that have been exported from a specific module. The basic syntax is: 

import * from <source-module>

Consider the following portion of the biz_set_1 module from which four statements are exported. These statements are designed to be shared with various teams:

biz_set_1 module

export $top10threats  // A search exported as a view
export $metrics  // A search exported as a view
export is_error  // A custom function
export roundif  // A custom function

You can import all of these items into a module by using a bulk single import statement. A bulk import statement uses a wildcard character ( * ) to import all of the items exported from the module you specify.

In the following example, all of the items exported from the biz_set_1 module are imported into the a-team module:

a-team module

import * from biz_set_1

You can use these imported items in the a-team module. The following example shows the top10threats view and the roundif custom function used in $search1 in the a-team module:

a-team module

import * from biz_set_1
$search1 = FROM top10threats SELECT score, roundif(score, 3) as newscore

Importing all items from multiple modules

You can import all of the items from different modules using separate bulk import statements. Using import * imports only the exported items from those modules.

In the following example all of the items exported from the biz_set_1 and biz_set_2 modules are imported into the a-team module:

a-team module

import * from biz_set_1
import * from biz_set_2
Note: Naming conflicts might occur if items from different modules have the same name. See Naming conflicts when importing items.

Import indexes and other datasets

The kinds of datasets that you can import are:

  • Indexes
  • Lookups
  • Saved searches
  • Views

The datasets inside a namespace are automatically available to every module in that namespace. Those datasets do not need to be imported into the modules in that namespace.

For datasets that reside in another namespace, such as the built-in namespaces used for indexes and apps, you must:

  • Have access to those datasets before you can import the datasets into a module.
  • Specify the path to the dataset.

For example, to import a specific index, such as the main index, use the following syntax: 

import <index_name> from ~indexes
Note: When importing an index, you can use a shortcut to specify the path to the built-in indexes namespace. The shortcut is the tilde ( ~ ) symbol.

For more information about namespaces, see Understanding SPL2 namespaces.

Import examples

When you use an import statement, it's important that you specify the correct path to the item you want to import. See Specifying import paths.

The following table shows examples of common import statements:

Type of import Example
Import a specific index import main from ~indexes
Import all indexes import * from ~indexes
Import all lookups into the target application import * from /apps.<app_name>.lookups
Import a specific lookup into the target application import my_lookup from /apps.<app_name>.lookups
Import a specific lookup that contains a special character, such as a dot ( . ) character. import 'my.lookup' from /apps.<app_name>.lookups

Import all lookups into the target application using an alias called "address".

To use a lookup that was imported with an alias you must preappend the alias before the lookup name, as show in the example.

import * as address from /apps.<app_name>.lookups

To use the my_lookup that was imported using the address alias, you would specify something like this:

... | lookup address.my_lookup CustID as cid OUTPUT CustAddress as cAddress