Importing items 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.

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, based on your current, destination module. See Specifying import paths.

Import an item

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

To import this view into your current module, annual_purchases, you use this import statement:

import purchases from 'Quarterly Purchases'

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. Because the module name contains a space, you must enclose the name in single quotation marks.

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, Quarterly Purchases and annual_purchases.The Quarterly Purchases module contains three search statements: $purchases, $qtr1_purchases, and $qtr1_errors. The module also contains a function statement called isError.

The $purchases and $qtr1_errors search statements have been exported as views. The isError function statement has also been exported. The purchases view, the qtr1_errors view, and the isError function are imported into the annual purchases module.

For example, to import two searches and a function that were exported from the Quarterly Purchases module, use this import statement:

import {purchases, qtr1_errors, isError} from 'Quarterly Purchases'

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

import purchases from 'Quarterly Purchases'
import qtr1_errors from 'Quarterly Purchases'
import isError from 'Quarterly Purchases'

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. Four statements have been exported from the biz_set_1 module. These statements are designed to be shared with various teams:

biz_set_1

export $top10threats  // This search is exported as a view dataset.
export $metrics  // This search is exported as a view dataset.
export isError  // This function looks for error code values greater than or equal to 400.
export roundif   // This function rounds values to a set number of decimal points if the value is greater than 1.

You can import all of these items into the A-Team module by using the following import statement.

A-Team

import * from biz_set_1

You can use these imported items in the A-Team module. For example, you can use the top10threats view dataset and the roundif custom function in a search as shown in $search1:

A-Team

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

When you create a custom function, you can add descriptions and examples in the form of documentation comments. When you import a custom function into a module and then use that function in a search, the documentation comments appear in the user interface (UI). See Documenting custom functions.

Importing all items into a subnamespace

Suppose there is a module, biz_set_2, that contains two custom functions statements and a custom data type statement which are designed to be shared with various teams. These statements have been exported:

biz_set_2

export count_sigfig_threats    // This function counts and rounds the number of threats to the specified significant figures.
export roundif  // This function rounds values to a set number of decimal points if the value is greater than .5.
export person  // This structured data type includes the firstname, surname, and age of a person.

You want to import these items into the A-Team module. However there already is a function called roundif in the A-Team module that was imported from the biz_set_1 module.

To resolve this ambiguity, you can import the items from the biz_set_2 module into a subnamespace in the A-Team module. A subnamespace is useful specifically when you want to import all of the exported items from a module.

The syntax to import all items into a subnamespace is:

import * AS <subnamespace-name> from <source-module>

The AS keyword is shown in uppercase in the syntax for readability. You can specify the AS keyword in uppercase or lowercase.

For more information about subnamespaces, see Import items into a subnamespace.

Here's an example. You can import all of the exported items from the biz_set_2 module into a subnamespace called biz2 in the A-Team module by using the following import statement:

A-Team

import * AS biz2 from biz_set_2

You can use these imported items in the A-Team module by qualifying the item name with the name of the subnamespace. For example, you can use biz2.roundif when you specify the function in a search statement, as shown in $search2:

A-Team

import * AS biz2 from biz_set_2
$search2 = FROM top10threats SELECT score, biz2.roundif(score, 2) AS newscore

Importing datasets

The datasets inside a namespace, such as index datasets and lookup datasets, are automatically available to every module in that namespace. Those datasets do not need to be imported into modules in that namespace.

For datasets that reside in another namespace, such as a nested namespace, you must have access to those datasets before you can import the datasets into a module.

Items with duplicate names

You can import an item into a module that already has an item with the same name. However, an error might be returned when you attempt to use the item if the software can't determine which item to use.

For example, if you import a custom function called isError and you have a search called isError, no error is returned because the items are different kinds. However, if you import a different custom function called isError, an error is returned when you attempt to use that function in a search.

You can avoid this issue by using one of these methods:

• Rename an item when you import it
• Import the item into a subnamespace
• Change the import statement for one of the items. Because the import statement is a pointer, you can either change the statement to rename the item, or change the statement to import the item into a subnamespace.

Rename when you import items

You can rename an item when you import it to avoid duplicate item names in your module. To rename an item when you import it, use an AS clause in the import statement.

The import syntax is:

import <item_name> AS <rename> from <source_name> 

For example, to rename the transactions view from the Q1_data module as qtr1_transactions, use this import statement:

import transactions AS qtr1_transactions from Q1_data

You can specify the AS keyword in uppercase or lowercase in your statement. For readability, uppercase is used in this example.

Import items into a subnamespace

Another way to avoid duplicate item names in a module is to import the items into a subnamespace. A subnamespace is a virtual namespace. You can import one or more items into a subnamespace.

The import statement syntax is:

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

The curly brackets { } are required around the list of items, even if only one item is specified. Using the curly brackets with the AS clause identifies this statement as an import into a subnamespace instead of a rename.

Importing an item into a subnamespace

Here's an example of the import statement when importing one item into a subnamespace:

import {qtr1_purchases} AS qtr_2021 from 'Quarterly Purchases'

Using an item imported into a subnamespace

To use an item that has been imported into a subnamespace, you must qualify the item name with the name of the subnamespace. For example, to use the qtr1_purchases view dataset in a search, you would qualify the dataset name with the name of the subnamespace:

$search = from qtr_2021.qtr1_purchases where categoryId="STRATEGY" ...

Importing into the local namespace

If your current location is the subnamespace, you can omit the AS clause in the import statement. The curly brackets { } are required.

import {qtr1_purchases} from 'Quarterly Purchases'

Importing multiple items into a subnamespace

Here's an example of the import statement when importing multiple items into a subnamespace:

import {qtr1_purchases, qtr2_purchases, qtr3_purchases, qtr4_purchases} AS qtr_2021 from 'Quarterly Purchases'

See also

Related information

Specifying import paths

Scope and precedence importing items

Exporting module items using SPL2

Related reference

Custom eval functions in the SPL2 Search Reference

Custom command functions in the SPL2 Search Reference

Custom data types in the SPL2 Search Reference