Create an SPL2 module

Use SPL2 modules to work with multiple SPL2 statements, such as searches and custom resources, while remaining in the same context.

An SPL2 module is a file that can contain multiple SPL2 statements, such as searches, custom functions, custom data types, and views that refer to specific sets of search results. Create a module if you want to work with multiple searches while remaining on the same browser tab, or write advanced searches that use custom functions and data types or refer to the results of other searches.

For more information about how SPL2 modules and statements work, see SPL2 modules and statements.

To create an SPL2 module, complete the following steps:
  1. Write and run searches in an SPL2 module

  2. Save an SPL2 module

Write and run searches in an SPL2 module

Use an SPL2 module to work with multiple searches in a single browser tab.

  1. From Splunk Home, select Search & Reporting in the Apps panel.
  2. On the Search page, in the Search, transform, and analyze data using SPL2 area of the page, select Search in SPL2 module.
    The SPL2 module editor opens in a new browser tab.
  3. In the Select data to search panel, select the index that you want to search and then select Apply.

    The SPL2 panel populates with an import statement and a search statement. The import statement makes your index available to searches in this module, and the search statement is what you use to actually search the data in your index.

    For example, if you select an index named main, then the following statements appear in the SPL2 panel:
    import main from ~indexes
    
    $search = search index=main

    Notice that the search statement starts with $search, which is the name of the search. Each search in the same module must be identified with a unique name.

  4. (Optional) Change the name of the search by replacing $search in the SPL2 panel.

    Be aware that search name must meet these requirements, or else the search returns a syntax error:

    • Start with a dollar sign ( $ ).

    • Use a letter as the first character after the dollar sign ( $ ).

    • Contain only letters, numbers, or the underscore ( _ ) character.

    The following example shows the same search as the previous step after it has been renamed from $search to $my_search1:
    import main from ~indexes
    
    $my_search1 = search index=main
  5. To run your search, do the following:
    1. Confirm that the time range picker is set to an appropriate time range for your search.
    2. Select the Run icon (This image shows an icon with a magnifying glass.).

    The search results panel displays the data returned by your search.

    Note: The search results panel displays a timeline that is based on an event field named _time. If you run a search that drops the _time field from your search results, then the timeline will not display as expected. For examples of searches that can prevent or cause this issue, see Drop event fields.
  6. For each additional search that you want to add to your module, do the following:
    1. In the Outline panel, select the Add new statement icon This image shows an icon with a plus sign.) and then select Statement.
      A new search statement is added to the SPL2 panel, and the Select data to search panel opens.
    2. In the Select data to search panel, select the index or dataset that you want to search and then select Apply.
      Note: You can branch a search by selecting it as the dataset for a subsequent search. Doing this allows you to progressively refine your searches by using the results from an initial base search as the starting dataset of your next search. See Branching SPL2 searches for more information.
      The SPL2 panel populates with the corresponding import statement and search statement.
    3. (Optional) Rename the search, if desired.
    4. To specify which search you want to run and see results from, do either of the following:
    • In the SPL2 panel, move your caret to the line that contains the search.
    • In the Outline panel, select the name of the search.

You now have an SPL2 module that contains one or more SPL2 searches.

The following image shows an example of an SPL2 module that contains 3 searches in addition to an import statement:

This image of the SPL2 module editor shows the main index imported into the module and three searches using SPL, SPL2, and SQL syntax.
You can save the module to retain the searches and other SPL2 items that you defined in the module, and optionally share or reuse those searches and items in other contexts. See Save an SPL2 module for more information.

Save an SPL2 module

Save your SPL2 module, and configure permissions to keep the module private or share it with other Splunk platform users.

When you save an SPL2 module, you can choose to keep the module private or allow other users of the Search & Reporting app to see, edit, or use the contents of the module.

  1. In the SPL2 module editor, select Save module.
  2. In the Module name field, enter a name for identifying the module.
    A module ID is automatically generated based on the module name that you specify.
  3. (Optional) To change the module ID, select Edit and then enter a different value in the Module ID field.
  4. (Optional) In the Description field, enter a description for the module.
  5. Choose whether to keep the module private so that only you can see its contents and run the searches it contains, or share the module so that other users of the Search & Reporting app can access it:
    OptionDescription

    Keep the module private

    1. Set the Namespaces toggle to Private.

    2. Select Save.

    Share the module

    To save the module as a shared module, complete these steps:
    1. Set the Namespaces toggle to App.

    2. Select Save module and configure permissions.

    3. (Optional) In the Configure permissions dialog box, specify the level of module access allowed to each role in the Splunk platform instance. For more information, see SPL2 module permissions.

    4. Select Save.

Your module is saved in the Search & Reporting app with the name, ID, and namespace that you specified.

You can navigate to the Modules page in the Search & Reporting app to see a list of all the SPL2 modules that are available to you. For more information, see Manage SPL2 modules.

There are a variety of ways that you can continue to work with the contents of your SPL2 modules. For example:

  • You can save a search as a report, alert, or dashboard. For more information, see the Creating reports, alerts, and dashboards chapter.

  • You can export a search as an SPL2 view, so that you or other users on the Splunk platform deployment can import that view into another SPL2 module and then use the search results as a dataset. For more information, see SPL2 views and the Exporting module items using SPL2 chapter.