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.

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 using a namespace alias

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

// This function counts and rounds the number of threats to the 
// specified significant figures.
export count_sigfig_threats    

// This function rounds values to a set number of decimal points 
// if the value is greater than .5. 
export roundif 

// This structured data type includes the firstname, surname, and 
// age of a person.
export 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 using a namespace alias in the A-Team module. A namespace alias is useful specifically when you want to import all of the exported items from a module.

The syntax to import all items into a namespace alias is:

import * AS { <alias-name> } from <source-module>

The curly brackets { } that surround the <alias-name> are required when specifying a namespace alias. 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 namespace aliases, see Import items into a namespace alias.

Here's an example. You can import all of the exported items from the biz_set_2 module into a namespace alias 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 namespace alias. 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 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 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

For more information about namespaces, see Understanding SPL2 namespaces.

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 resolve this error by 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 using a namespace alias:

• Rename an item when you import it
• Import the item using a namespace alias

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 using a namespace alias

Another way to avoid duplicate item names in a module is to import the items using a namespace alias. You can import one or more items using a namespace alias.

The import statement syntax is:

import {<item_name>, <item_name>, ...} AS <namespace_alias> 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 using a namespace alias instead of a rename.

Importing an item using a namespace alias

Here's an example of the import statement when importing one item using a namespace alias:

import {qtr1_purchases} AS qtr_2024 from 'Quarterly Purchases'

The item you've imported is now identified as qtr_2024.qtr1_purchases.

Using an item imported with an alias

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

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

Importing multiple items using a namespace alias

Here's an example of the import statement to import multiple items using a namespace alias:

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

These items are now identified as:

• qtr_2024.qtr1_purchases
• qtr_2024.qtr2_purchases
• qtr_2024.qtr3_purchases
• qtr_2024.qtr4_purchases

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 using namespace alias called "address" to avoid naming collisions. Import all lookups into the target application.	import * AS address from /apps.<app_name>.lookups To invoke this lookup use: ... | lookup address.my_lookup CustID AS cid OUTPUT CustAddress AS cAddress

See also

Related information

Specifying import paths

Scope and precedence importing items

Exporting module items using SPL2

Understanding SPL2 namespaces

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