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:
- 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.
- (Optional) Filter for your report in the filter bar.
- 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.
- 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.
Add reports and saved searches from the Reports tab
Follow these steps to add a report or saved search to your dashboard directly from the Reports tab.
- Navigate to the Reports tab. In Reports, saved searches are called reports.
- Select your report to open it in its individual page.
- Select the Add to Dashboard drop-down list in the top toolbar.
- Select either Existing Dashboard or New Dashboard.
- Existing Dashboard lists existing Dashboard Studio and Classic Simple XML dashboards.
- New Dashboards provides a modal to create a new Dashboard Studio or Classic Simple XML dashboard.
- Follow the UI instructions for choosing an existing dashboard or creating a new dashboard.
- Verify the selections in Advanced Panel Settings. The default setting for Panel Powered By is Report. Keeping the default setting to Report retains the report's metadata, such as schedule, acceleration, and permissions.
- (Optional) Select Inline Search to copy the report's search and time range. The inline search detaches from the report's setting constraints, exists only in the dashboard, and has no external dependencies. For example, if a user changes the original report, those changes don't pass on to the inline search because the inline search exists independently from the report.
- Select Save to Dashboard.
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.
- Select your visualization. Selected visualizations highlight with a blue border.
- Select + Set up primary data source in the Data sources section of the Configuration panel.
- Create a new search or select a saved search.
- To create a new search, select + Create search.
- In the SPL query text box, add your search.
- A search using
savedsearch
might look like the following:| savedsearch <your saved search's name>
. - A search using
loadjob
might look like the following:| loadjob savedsearch="admin:<your app's name>:<your saved search's name>"
- A search using
- 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.
- Select the visualization that you want to use with the saved search or report. Selected visualizations highlight with a blue border.
- Navigate to the Data sources section of the Configuration panel.
- Select the edit icon next to the data source's name.
- Change the Data source name to something easily identifiable, such as
reportNoScheduleNoRefresh
. - 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:
- Open the Source code editor of your dashboard.
- Navigate to the
dataSources
stanza of the dashboard definition. - Identify which data source you want to change to a saved search or report.
- Replace the data type from
ds.search
tods.savedSearch
. - Add the
ref
property to theoptions
stanza and include the exact name of your saved search or report. - Add the
app
property to theoptions
stanza and include the name of the app the saved search or report belongs to. - 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.
Chain searches together with a base search and chain searches | Use mock data with ds.test |
This documentation applies to the following versions of Splunk® Enterprise: 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1
Feedback submitted, thanks!