After you run a search that returns interesting or useful results, you may want to save the search, so the search can easily be run again without having to retype the search string. Or you may want to save the results of that search run so you and others can review those results at a later time. This topic covers:
- Manually saving searches via the Splunk Web UI.
- Manually saving searches by updating
- Actions that cause Splunk to automatically save searches.
- Sharing the results of searches with others.
- Managing saved search navigation.
Manually save a search
If you've just designed a search that returns useful results and you want to save it, it's easy to do so through the Splunk Web UI once a search is running, finalized, or completed. You can also define a new saved search manually in
savedsearches.conf. See the following subsections for details on these methods.
At minimum, a saved search definition includes the search string and the time range associated with the search (expressed in terms of relative time modifiers). It should also include a search name--this is what appears in the Searches & Reports dropdown after the search is saved.
Note: You can change the navigation rules for your app so that searches are saved to a location in the top-level navigation other than Searches & Reports. For more information, see Managing saved search navigation, below.
Save a running, completed, or finalized search from the timeline view
When you run a search in the timeline view, you can manually save it through Splunk Web by clicking the Save... button that appears above the search bar and then selecting Save search... to open the Save Search dialog.
When the Save Search dialog opens, it is populated with the Search string and Time range (expressed with relative time modifiers) of the search you're saving. You can modify that information before you save it. You must give the saved search a unique Name. This name will appear in the "Searches & Reports" list in the app navigation bar near the top of the page after you save the search.
By default, any search you save is initially private and only available to you. If your permissions allow it, the Save search dialog enables you to reset the search permissions so that every user of the app you're you're using when you save the search has "read-only" access to it (which means that they can run the search from the Searches & Reports list but they can't edit it or change its permissions).
However, if you have an Admin-level role, you can go into Manager > Searches and reports and narrow or widen the potential usage of the saved search by further redefining its permissions. For example, you could make it "globally" available to everyone that uses your Splunk implementation. Or you could narrow the saved search permissions so that only specific roles within the current app can use it. You can also arrange for particular roles or users to have "write" access to the saved search, enabling them to edit its definition.
Accelerate the search so it runs faster next time
If your search has a large number of events and is slow to complete, you may be able to accelerate it so it completes faster when you run the search again in the future. To do this, you have to select Turn on acceleration in the Acceleration section of the Save Search dialog box.
Note: You won't see an Acceleration section if:
- Your permissions do not enable you to accelerate searches. You cannot accelerate searches if your role does not have the
- Your search does not qualify for acceleration. For more information, see the subtopic "How searches qualify for report acceleration," below.
How does Splunk accelerate the search? When you save a search with Turn on acceleration selected, Splunk runs a background process that builds a data summary based on the search. When you next run the search, Splunk runs it against this summary rather than the full index. Because this summary is smaller than the full index and contains precomputed summary data relevant to the search, the search will complete much quicker than it did when you first ran it.
When you turn on acceleration for a search, you must choose a Summary Range value such as 7 Days or 3 Months. This range represents the approximate span of time that always covered by the summary at any given moment, once it is built. When the summary is built and you run this search again, to get full acceleration benefits the search must have a time range that fits within this summary range. For more information, see the subtopic "Select a summary time range," below.
Note: The data summaries discussed here operate on principles similar to those of traditional summary indexes, but that's where their resemblance ends. The data summaries that are created for search acceleration purposes are not summary indexes. For more information about search acceleration and summary indexing, and information about why one might prefer one method over the other, see "About report acceleration and summary indexing" in the Knowledge Manager Manual.
Search mode and report acceleration: Report acceleration only works for searches that have Search Mode set to Smart or Fast. If you select the Verbose search mode for a search that benefits from report acceleration, it will run as slow as it would if it were not accelerated at all. For more information about the Search Mode settings, see "Set search mode to adjust your search experience" in the Search Manual.
How searches qualify for report acceleration
For a search to qualify for acceleration, it must use a reporting command (such as
top). In addition, any search commands before the first reporting command in the search string need to be streaming commands. (Nonstreaming commands are allowed after the first reporting command.)
We provide examples of qualifying and non-qualifying searches in "Manage report acceleration," in this manual.
Select a summary time range
When you select Turn on acceleration, you select an appropriate Summary Range for the summary that Splunk will build for the search. This selects the approximate range of time that the summary covers; for your future runs of the search to benefit from acceleration, they need to have ranges that fall within the summary range.
For example, if you choose a Summary Range of 7 Days, you're saying that going forward, you want Splunk to build and maintain a summary that always covers at least the last seven days. As time passes, Splunk will delete data from this summary that is older than seven days while it continues to summarize incoming new data.
Once this summary is built, this search will complete relatively quickly as long as you run it over time ranges that fall within the past seven days. If you run the search over the past 10 days, it'll get acceleration benefits for the portion of the search that covers the last seven days, but the portion of the search that covers the remaining 3 days will have to run over raw data and will not be accelerated.
The same goes for the other Summary Range settings. Choose 1 Month if you plan to run the search over time ranges that are fall within the last 30 days. Choose 1 Year if you anticipate that you'll need to run the search over time ranges that fall within the past year. Keep in mind that larger summaries take longer for Splunk to generate at first and will consume more storage resources.
Note: If you don't want there to be any restrictions over when you can run a search and still get acceleration benefits, choose All Time.
Manage your report acceleration summaries
Splunk provides a Manager page for this feature at Manager > Report Acceleration Summaries. On this page you can review the report summaries to which you have access. You can see the searches that apply to them, view their build progress, verify their consistency, rebuild them when they are damaged, delete summaries that are obsolete or which are taking up needed space, and more.
It's important to note that as the number of summaries in use by your implementation stacks up, you may encounter storage and performance impacts. This is because search acceleration summaries require storage space, and to keep them updated Splunk has to run backgrounded searches on new data every 10 minutes. The Report Acceleration Summaries page enables you to quickly identify summaries that are taking up more space than they are worth, given the frequency of their use.
For more information about search acceleration, including an explanation of what is happening behind the scenes, a discussion of summary storage and performance considerations, and more tips on summary management with the Report Acceleration Summaries page, see "Manage report acceleration," in this manual.
Create a new saved search in Manager
When you are saving a new search, it's easiest to just run the search and then use the "Save search" dialog box to save it. This method enables you to test the search before you save it.
You can also manually create new saved searches in Manager. Navigate to Manager > Searches and reports and click New to define and add a new saved search. To define the search you'll need to provide the same essential information required by the Save search dialog: the Search name, the search string (in the Search field), and the Time range (expressed with relative time modifiers). You can optionally enter a search description that explains what the search does and/or how it should be used.
The Acceleration controls will be available if your search qualifies for automatic search acceleration and your permissions enable you to make use of them. You use these controls to enable the search to run faster in the future. Their functionality is the same as the Acceleration controls on the Save Search dialog. For more information about them, see the section on search acceleration, above.
Note: As mentioned earlier in this topic, not all searches qualify for report acceleration; at the very least they need to include a reporting command. For more information, see "Manage report acceleration" in the Knowledge Manager Manual.
You can optionally select Schedule this search. This opens up a variety of fields that enable you to schedule the search to run on a regular schedule, define triggering conditions for an alert based on the search, and set up alerting actions (what happens when the alert is triggered). In other words, you can use it to turn your search into an alert or a scheduled search.
For more information about creating alerts see "About alerts," in the Alerting Manual. This topic also has information about alerting options that are only available through the Searches and reports detail page in Manager, such as the capability to set expiration times for alert records in the Alert Manager or the "add to RSS feed" alerting condition.
For more information about defining scheduled searches (searches that run on a schedule and which send search results via email or launch a script each time they run), see "Create a scheduled search" in the Alerting Manual.
The Searches and reports detail page in Manager is also the only place in the Splunk Web UI where you can enable summary indexing for a saved search (you can also configure summary indexing for a search by modifying
savedsearches.conf). For more information about summary indexing, see the topic "Enable summary indexing for a search," in the Knowledge Manager Manual.
You can edit and update searches listed on the Searches and reports page if you have "write" permissions for them. For more information about permissions, see "Manage knowledge object permissions" in the Knowledge Manager Manual.
Configure a saved search in savedsearches.conf
When you save a search via the Splunk Web UI or Manager, Splunk automatically adds a configuration stanza for that search to
savedsearches.conf. The UI validates your changes, and you won't have to reboot the system to apply searches created via UI methods. But if you prefer to work with saved searches directly through configuration files, you certainly can.
For more information about configuring saved searches and alerts in
savedsearches.conf, see the spec file for
savedsearches.conf and the "Configure alerts in savedsearches.conf" topic in the Alerting Manual.
When Splunk automatically saves your searches
The preceding sections show you how to manually save a search you've just run. But there are also many actions you'll perform as a Splunk user that cause Splunk to automatically save your search.
Splunk automatically saves searches when you create alerts, dashboard panels, reports, and scheduled searches via the Splunk Web UI (these are options you can select after clicking Create for a running, completed, or finalized search).
Note: When Splunk automatically saves a search as the result of the creation of an alert, dashboard, report, or scheduled search, it does not add the name of that search to the Searches & Reports list in the app navigation bar near the top of the page after you save the search.
Creating dashboard panels
All dashboard panels are based on searches. If you run a search and then use the Create Dashboard Panel dialog to create a new panel for a new or preexisting dashboard, Splunk automatically saves the search that powers the panel as well. After the panel is created, use the dashboard Edit search dialog to choose a different saved search for the panel, or just edit the current search inline. When you edit the panel's search inline, the original saved search is not updated with those changes.
Note: In the Add to dashboard dialog, saved search permissions are managed at the dashboard level (in the dialog's Dashboard step).
- If the dashboard panel you are creating is going on an existing dashboard, the search you are associating with it takes on the same permissions as that dashboard.
- If the dashboard panel that you are creating is going on a new dashboard, and you have admin-level permissions, you can keep the dashboard private, or share the dashboard as read-only with all users of the current app. (If you do not have admin-level permissions the new dashboard will be private--viewable only by you--by default. The search you are associating with the dashboard panel will take on the permissions of the new dashboard.)
For more information about creating panels for dashboards, see the topic "Create and edit dashboards via the UI," in this manual.
Creating alerts and scheduled searches
Alerts are based on saved searches; they can be either real-time searches or scheduled searches depending on the type of alert that you define. Splunk saves the search and determines whether it runs in real-time or is a historical, scheduled search during the alert creation process.
Scheduled searches are essentially scheduled alerts that are designed to trigger each time they run. They're useful for things like sending reports via email to a set of recipients on a regular schedule, like "every day at midnight" or "every Monday, Wednesday, and Friday."
Note: You can also manually set up an existing saved search as an alert or scheduled search via Manager > Searches and Reports.)
When you use the Report Builder to create a report based on a search, Splunk automatically saves the base search.
Note: This is the only method of saving a search that includes chart formatting parameters with the search. If your search includes reporting commands, and you want the chart that the search produces to include custom formatting (so that it displays a pie chart rather than the default bar chart and has specific text for the title, x-axis, and y-axis, for example) be sure to save it as a report from the Report Builder. If you save it as a search, any formatting you set up for the chart in the report builder will be lost. This is especially important if you intend to display the chart in a specific way on a dashboard.
For more information about defining and saving reports with the Report Builder, see "Define reports with the Report Builder" and "Save reports and share them with others," in the Splunk Data Visualizations Manual.
Save search results
Saving search results is different from saving the search itself. When you save a search, you're saving the search string and time range (as well as any chart or table formatting associated with the search), so it can easily be run again in the future. When you save the results of a search, you are saving the outcome of a specific search job.
If you just want to save the results of a search, click Save and then select Save results.
When you select Save results, Splunk saves the search job. "Saving a search job" means that Splunk prevents the search job from expiring--by default all search jobs are set to expire (self delete) after a certain amount of time. You can save results for both historical searches and currently running real-time searches. You can examine the results later by finding the job on the Jobs page. You get to the Jobs page by clicking the Jobs link in the upper-right hand corner of the Splunk interface.
For more information on managing search jobs through the Job Manager, see "Supervise your search jobs with the Job Manager" in this manual.
Sharing search results is different from sharing a saved search. When you share search results you are making the results of a particular search job available to other people. If you would like to do this, you have two options: you can save & share your search job, or you can export the results to a file and send that file to others.
Saving and sharing results. To do this, click Save and then select Save & share results... When you do this, Splunk saves the search job just as it does when you select Save results. In addition, Splunk gives you a URL. You can share this URL with other interested parties, who can use it to view the search results for the job it links to as long as they have access to your instance of Splunk and the job exists in the system.
Export the event data to a file. You can export the event data from your search job to a csv, xml, json, or raw data file, and then archive it or use it with a third-party charting application. To do this, run the search, and then select the Export link that appears above your search results:
You can set a limit for the number of events you want to export, or you can go ahead and export all the events in your search. Keep in mind that some searches return enormous numbers of events, so take precautions as necessary for your situation.
When you save a search, it should appear in one of the drop-down lists in the top-level navigation menu. In the Search app, for example, new searches appear in the Searches & Reports list by default.
If you have write permissions for an app, you can change this default location, and even set things up so that searches with particular keywords in their names are automatically placed in specific categories in the navigation menu. For example, you can set things up so that Splunk automatically places saved searches with the word "website" in their name into a list of website-related searches in the navigation menu. You can also move searches from the default list to different locations in the top-level navigation menu.
For an overview of the navigation setup options that are available for saved searches and reports, see "Define navigation for saved searches and reports" in the Knowledge Manager manual. For the app navigation setup details, see "Build navigation for your app" in the Developer manual.
Managing saved searches with Splunk's REST API
You can create and manage saved searches using Splunk's REST API. Refer to the following documents in the Splunk REST API Reference:
- Search page of the Splunk REST API reference
Scroll to the saved/searches/* endpoints.
- Splunk REST API basics
If you are new to using the Splunk REST API.
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has around saved searches.
Create aliases for fields
Manage saved searches
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18