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 a single 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:

syntax

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 isError  // A custom function
export roundif  // A custom function

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

a-team module

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 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 import statements. Using import * imports only the exported items from those modules. For example:

a-team' module

import * from biz_set_1
import * from biz_set_2

Naming conflicts might occur if items from different modules have the same name. See Resolving 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 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.

Resolve naming conflicts when importing items

When you import items into a module, naming conflicts can arise:

• The module you are importing into might already contain an item with the same name.
• If you import items from multiple modules, the items in different modules might have the same name.

Importing an item with the same name as an existing item

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 changing the import statement. Because the import statement is a pointer, you can either rename the item when you import it or specify 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. Use an as clause in the import statement to rename the item.

The import syntax is:

import <item_name> as <rename> from <source_name> 

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

import transactions as qtr1_transactions from qtr1_data

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 module

export count_sigfig_threats  // A custom function
export roundif // A custom function
export person  // A custom data type

You want to import these items into the a-team module. However there is already 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:

syntax

import * as <alias-name> from <source-module>

The following example shows using a namespace alias called biz2 to import the items from the biz_set_2 module into the a-team module:

a-team module

import * as biz2 from biz_set_2

The three items from the biz_set_2 module are imported with these names:

results

biz2.count_sigfig_threats
biz2.roundif
biz2.person 

You can use these imported items in the a-team module by specifying the item name with the namespace alias. You can use biz2.roundif when you specify the function in a search statement, as shown in $search2 as shown in this example:

a-team module

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

For more information about namespace aliases, see Import items into a namespace alias.

Importing items from different modules

When you import items from different modules naming conflicts can arise, especially if you import all of the items from those modules using import * statements. The following sections describe various scenarios that result in naming conflicts

Importing items that result in the same name

When you import items with the same name an error is returned because of an ambiguous reference to that name.

Here are some examples where the ambiguous reference is to the name top10threats:

Scenaro	Import example
Items from different modules have the same name	import top10threats from incidents_team import top10threats from response_team
Renaming an items results in multiple items with the same name	import top10threats from incidents_team import hot_threats as top10threats from response_team
Importing all items using a namespace alias that results in items with the same name.	import top10threats from incidents_team import * as top10threats from response_team

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 'quarterlypurchases'

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