Scope and precedence importing items

When items are exported from a source, those items are made public. However, to use those items you must have access to the module from which the items were exported. And, you must import those items into the module in which you want to use the exported items.

When importing items, it's important that you understand scope and precedence.

Scope

Scope defines which items are available for you to use from your current module. Your current module is the module in which you are actively creating searches.

The following list defines what is "in scope" for you to use from your current module:

In scope	Description
Items in the current module	Any item created in a module is available for you to use inside that module.
items that are imported	Items that you have imported from other modules are available for you to use in searches in your current module.
Items in the namespace where the current module resides	Items, such as datasets, in a namespace are available for you to use in your current module without importing those items.

Scope examples

In the following image, your current module is the response_team module.

What you can use when the response_team module is the current module is described in the following table:

Type of item	Items in scope	Description
Datasets	emea_threats emea_sites	Because the response_team module is in the emea namespace, you can use every dataset in the emea namespace.
Statements	$top10threats count_sigfig_threats	The response_team module contains two statements, both of which that have been exported. Since the response_team module is the current module, you can use these statements. The audit_team module contains two statements, but neither of them have been exported. You can't import the statements from the audit_team module into the response_team module until the statements in the audit_team module are exported.

For comparison, suppose the current module is the audit_team module, as shown in this image:

Suppose your current module is the the audit_team module, and you have access to the response_team module. The following table describes what you can use while creating searches in the audit_team module:

Type of Item	Items in scope	Description
Datasets	emea_threats emea_sites top10threats (view)	Because the audit_team module is in the emea namespace, you can use every dataset in the emea namespace. The search statement from the response_team module has been imported as a view dataset into the audit_team module.
Statements	$historical_threats $metrics	The audit_team module contains two statements, neither of which that have been exported. Since the audit_team module is the current module, you can use these statements. The response_team module contains two statements, both of which have been exported. Since you have access to the response_team module, you can use any items that have been exported from that module.

Precedence

When you refer to an item in a search, such as the name of dataset, view, or function, SPL2 resolves the reference to the item by finding the matching item at is "in scope". See Scope.

If there are multiple items in scope that match the reference, for example if the items have the same name and are the same kind of item, then precedence rules determine which item to use.

Precedence rules

The following list shows the precedence rules order for items:

1. Local. Items created inside a module are local to that module and take precedence over items that are imported or built-in.
2. Imported
3. Namespace, for datasets only
4. Built-in

Precedence examples

Here are a few precedence examples:

• Suppose you create a function called isError in a module. If the module also has an imported function called isError, then when the function is used in a search statement, the local isError function is used. The imported function is ignored. Local items take precedence over imported items.

• Suppose you import a function called if into your module. When the function is used in a search statement, the imported if function is used instead of the built-in if function. The built-in function is ignored. Imported items take precedence over built-in items.

• If one item is a function and the other item is a view, then even though the items have the same name there is no conflict because the items are different kinds of items. SPL2 determines which item to use based on how the item is used in the search. Where and how you specify functions in a search is different than where and how you can specify views.

• If both items are functions with the same name but have a different number of arguments, the function that matches the arguments specified in your search is used. However, if both functions have the same number of arguments an error is returned.

Avoiding precedence errors

To avoid precedence errors, you can use one of the following techniques:

• Rename an imported item
• Import items into a subnamespace inside the module.

For more information, see Items with duplicate names.

See also

Related information

Importing items

Specifying import paths