
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 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'
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 ./lookups
|
Import a specific lookup into the target application | import my_lookup from ./lookups
|
Import a specific lookup that contains a special character, such as a dot ( . ) character. | import 'my.lookup' from ./lookups
|
Create a subnamespace called "lookups" to avoid naming collisions. Import all lookups into the target application. | import * AS lookups from ./lookups
|
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
PREVIOUS Exporting module items using SPL2 |
NEXT Specifying import paths |
This documentation applies to the following versions of Splunk® Cloud Services: current
Feedback submitted, thanks!