Use reports and saved searches with ds.savedSearch

ds.savedSearch brings in reports or saved searches within Dashboard Studio. You can use the ds.savedSearch data source to schedule saved searches to run on a particular frequency and store the results, which lightens processing loads and concurrent search limits. For example, if 50 users access a particular dashboard, panels with a scheduled saved search don't run the search 50 times, while panels with a non-scheduled search of the type ds.search might.

Dashboards in the Search & Reporting app that use reports transfer as JSON stanzas of type ds.savedSearch when you open them in Dashboard Studio.

Concurrency limits

If you have multiple saved searches in your dashboard, your dashboard only runs as many searches as your concurrency limit. Your limits.conf file lists concurrency limits for different types of searches. For example, if your concurrency limit is 3 and you have 5 saved searches, the first 3 saved searches in the queue run, but the last 2 don't. Concurrency limits prevent scheduled searches from queueing indefinitely.

For dashboards with more saved searches than the concurrency limit, use an ad hoc or inline search with the savedsearch command to call the saved search. An ad hoc or inline search creates a scenario where searches that exceed the concurrency limit still queue and run when capacity allows.

To learn more about inline searches, see Inline searches in the Dashboards and Visualizations with SXML manual.

For a list of settings for search concurrency limits, see Concurrency in the Admin Manual.

If you are using lookups in your search, make sure you've set the lookup permissions to "global".

Access reports and saved searches

To call a saved search or report, you need the exact name of the report you want to use and the app name of the original saved search or report. You can find details about your saved searches and reports from Searches, reports, and alerts or in the Reports tab.

The following steps show how to access a saved search or report from Searches, reports, and alerts or in the Reports tab:

1. Navigate to your preferred section.
   • Select the Settings drop-down list and choose Searches, reports, and alerts.
   • Select the Reports tab for a table of all saved searches and reports. In Reports, saved searches are called reports.
2. (Optional) Filter for your report in the filter bar.
3. Find the details of your saved search or report.
• In Searches, reports, and alerts, the column names of the table show the details about the saved search or report.
• In Reports, select the chevron icon next to your report for details about the report.
4. Make a note of the details needed for calling a saved search or report. You will need the following:
   • The exact name of the report you want to use.
   • The app name of the original saved search.

For more details about reports, see Create and edit reports in the Reporting Manual.

Properties for calling your report or saved search

The following is a table of Search Processing Language (SPL) commands and a dashboard option you can use to call your search:

Property	Type	Details
savedsearch	SPL command	savedsearch always runs a new search and accepts tokens.
loadjob	SPL command	loadjob returns cached results well.
ref	dashboard option	ref works best for displaying data.

For more details about savedsearch and loadjob, see savedsearch and loadjob in the Search Reference manual.

Handling cached results

Depending on how you call your saved search, scheduled and non-scheduled saved searches handle cached results differently. The following table details the different cached results behavior with each property you can use to call your saved search.

Property	Scheduled saved search	Non-scheduled saved search
savedsearch	Always runs a new search.	Always runs a new search.
loadjob	Attempts to load cached results from the saved search. If no cached results exist, loadjob returns the following error. (Error in 'SearchOperator:loadjob': Cannot find artifacts...)	Attempts to load cached results from the saved search. If no cached results exist, loadjob returns the following error. (Error in 'SearchOperator:loadjob': Cannot find artifacts...)
ref	Attempts to load cached results from the saved search. If no cached results exist, ref runs the search.	Runs the search whether or not there are cached results.

Calling a report or saved search with an SPL command

You can use savedsearch or loadjob to call a saved search or report. Each Search Processing Language (SPL) command has different capabilities. For example, savedsearch can accept tokens.

The following steps are an example of using the SPL command savedsearch or loadjob to gather data for a visualization.

1. Select your visualization. Selected visualizations highlight with a blue border.
2. Select + Set up primary data source in the Data configurations section of the Configuration panel.
3. Create a new search or select a saved search.
   1. To create a new search, select + Create search.
   2. In the SPL query text box, add your search.
      1. A search using savedsearch might look like the following: | savedsearch <your saved search's name>.
      2. A search using loadjob might look like the following: | loadjob savedsearch="admin:<your app's name>:<your saved search's name>"
4. Select Apply and close.

For more details about savedsearch and loadjob, see savedsearch and loadjob in the Search Reference manual.

Calling a report or saved search with the ref property

You can use the ref dashboard option to call a report or saved search. When using the ref property, you must reference a saved search or report by its exact name. Additionally, you must use the app property to specify which app the saved search or report belongs to. If no app is specified, the Splunk platform assumes the report came from the app in which the dashboard resides.

Change the data source's name

Before setting the ref property, you might want to change the data source's name to a name that's easily identifiable in the dashboard definition.

1. Select the visualization that you want to use with the saved search or report. Selected visualizations highlight with a blue border.
2. Navigate to the Data configurations section of the Configuration panel.
3. Select the edit icon next to the data source's name.
4. Change the Data source name to something easily identifiable, such as reportNoScheduleNoRefresh.
5. Select Apply and close.

Add the ref property to the dashboard definition

The following steps are an example of using the ref dashboard option to call a report or saved search:

1. Open the Source code editor of your dashboard.
2. Navigate to the dataSources stanza of the dashboard definition.
3. Identify which data source you want to change to a saved search or report.
4. Replace the data type from ds.search to ds.savedSearch.
5. Add the ref property to the options stanza and include the exact name of your saved search or report.
6. Add the app property to the options stanza and include the name of the app the saved search or report belongs to.
7. Select Apply and close.

This example shows a data source type set to ds.savedSearch.

"reportNoScheduleNoRefresh": {
  "type": "ds.savedSearch",
  "options": {
    "ref": "Top 100 sourcetypes in the last 24 hours",
    "app": "search"
  }
},

About the app property

The default assumption is that the saved search you're using lives in the app you're working in. If you created your saved search within any app other than Dashboard Studio, you must use the app option and set it to the app where you originally saved the saved search. For example, if you created a saved search in an app called "my-app", the stanza would look like the following:

"reportNoScheduleNoRefresh": {
  "type": "ds.savedSearch",
  "options": {
    "ref": "Top 100 sourcetypes in the last 24 hours",
    "app": "my-app"
  }
},

ds.savedSearch options

Unlike ds.search, the ds.savedSearch data source type does not work with the name or query options. The only options you can use are ref and app, as well as refresh and refreshType for searches that are not scheduled searches. For example, the following saved search refreshes at five second intervals:

"reportNoScheduleWithRefresh": {
  "type": "ds.savedSearch",
  "options": {
    "ref": "Current Time",
    "refresh": "5s",
    "refreshType": "interval"
},

Scheduled saved searches

When editing a data source in the source code, if you are referencing a scheduled saved search, your dashboard works with that schedule regardless of whether you set the refresh or refreshType options. For example, if a report from the Search & Reporting app has been scheduled to run at the top of every minute, setting the refresh interval to five seconds in the JSON stanza will have no effect. The scheduled search will continue to run at the top of every minute. The same is true for any settings that apply to the data source type in the defaults section of the dashboard definition.

If the report is a scheduled search, but its first scheduled run has not yet completed, the search will run automatically the first time it's added to the dashboard definition.

Use a saved search as a base search for scheduled chain searches

You can use the ds.savedSearch data source as a base search in the same way that you can use ds.search as a base search. The ds.chain data source accepts all of the options that it would if the base search was of type ds.search. For example:

"baseReportNoScheduleWithRefresh": {
  "type": "ds.savedSearch",
  "options": {
    "ref": "Current Time",
    "refresh": "5s",
    "refreshType": "interval"
  }
},
"postReportNoScheduleWithRefresh": {
  "type": "ds.chain",
  "options": {
    "query": "| eval count=count-1500000000",
    "extend": "baseReportNoScheduleWithRefresh"
  },
  "name": "Data Source Name: Post Report - No Schedule, With Refresh"
},

For more information on chain searches, see Chain searches together with a base search and chain searches.

Remember, if you have the cancelJobsOnFocusLoss option, or any other options set in the defaults section of the dashboard definition, it most likely affects the data source of type ds.search. Since ds.savedSearch is a different type, these searches will not be affected by that setting and will continue to run in the background. You must not set cancelJobsOnFocusLoss for the ds.savedSearch data type since these searches are usually scheduled and depend on being run uninterrupted.