Data source options and properties
The options
field of a data source stanza is where you can set various properties. Following the JSON format, each property setting must be enclosed in quotes unless it is a boolean value (true, false) or a number. Options other than the last one set must end in a comma.
The following table lists the options that are available for you to use to modify your dataSource stanzas:
option | type | default | description |
---|---|---|---|
app | string | search | Only for ds.savedSearch . Define the app that is associated with a report, or saved search, that you want to use.
|
query | string | N/A | Write your SPL search using the query .
|
queryParameters.earliest | string | N/A | All data source time ranges are controlled by a default Global time range picker. To override that setting, specify the earliest time to search for events. Choose from year (y), month (m), week (w), day (d), minute, (m), or second (s), or 0 for all time. For example, if you want to run a search that runs for all time, see The queryParameters example. |
queryParameters.latest | string | N/A | All data source time ranges are controlled by a default Global time range picker. To override that setting, specify the latest time to search for events. Choose from year (y), month (m), week (w), day (d), minute, (m), or second (s), or an empty string for all time. For example, if you want to run a search that runs for all time, see The queryParameters example. |
ref | string | N/Z | Only for ds.savedSearch . Enter the exact name of the report you are using. This will allow the Dashboard Studio to pull the report from its location.
|
refresh | string | N/A | Specify the refresh interval with a time expression. For example, "5s" for five seconds or "1m" for one minute. See refreshType and refresh example. |
refreshType | (delay | interval) | delay | Indicate the starting time for a search to refresh. Use delay to start the countdown to refresh when the search is done. Use interval to count down when the search is dispatched. See refreshType and refresh example.
|
The queryParameters option example
The following example allows a user to specify a time span for a search to run, overriding the default value set using the Time Range Picker for this data source and also changes the title of the resulting pie chart. It uses the option queryParameters
:
source code
Expand this box to see the complete dashboard definition. You can copy/paste it into your own instance to view how this inputs work with queryParameters
.
{ "visualizations": { "viz_chart1": { "type": "splunk.pie", "options": {}, "dataSources": { "primary": "search_1" }, "description": "Chart of Top Sourcetypes between $TimeRange.earliest$ and $TimeRange.latest$" } }, "dataSources": { "search_1": { "type": "ds.search", "options": { "queryParameters": { "earliest": "$TimeRange.earliest$", "latest": "$TimeRange.latest$" }, "query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)" } } }, "inputs": { "input_1": { "type": "input.timerange", "title": "Select a time:", "options": { "token": "TimeRange", "defaultValue": "-24h,now" } } }, "layout": { "options": { "submitButton": false, "height": 1250, "display": "auto-scale", "width": 1200 }, "globalInputs": [ "input_1" ], "structure": [ { "item": "viz_chart1", "type": "block", "position": { "x": 250, "y": 80, "w": 680, "h": 530 } } ], "type": "absolute" }, "title": "Time Picker Input Example", "description": "Add a time range picker to modify a search time span." }
refreshType and refresh property example
If you add the refreshType
and refresh
options to your data source, the visualization will refresh automatically at the interval you specify. In this case, refreshType
is set to delay the refresh until the end of the search at an interval of 10 seconds.
Don't specify default intervals of time that are too short in dashboards with many visualizations. Examples that use a refresh interval of under 1 minute are only appropriate for simple dashboards with few visualizations . Any interval less than one minute might not give the search jobs enough time to run, or may have a heavy performance impact on your dashboard. You can specify a string with the interval, such as "1m" for one minute. If you just specify an integer, without a time unit, the default unit is seconds.
Specifying these settings in the stanza overrides any refresh
and refreshType
setting in the defaults section of the dashboard definition.
"dataSources": { "search_1": { "type": "ds.search", "options": { "queryParameters": { "earliest": "$TimeRange.earliest$", "latest": "$TimeRange.latest$" }, "refreshType": "delay", "refresh": "10s", "query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)" } } },
The following dashboard definition is a modified version of the queryParameters
dashboard. The refresh
and refreshType
options have been added.
queryParameters and refresh options example
source code
Expand this box to see the complete dashboard definition. You can copy/paste it into your own instance.
{ "visualizations": { "viz_chart1": { "type": "splunk.pie", "options": {}, "showLastUpdated": true, "showProgressBar": true, "dataSources": { "primary": "search_1" }, "description": "Chart of Top Sourcetypes between $TimeRange.earliest$ and $TimeRange.latest$" } }, "dataSources": { "search_1": { "type": "ds.search", "options": { "queryParameters": { "earliest": "$TimeRange.earliest$", "latest": "$TimeRange.latest$" }, "refreshType": "delay", "refresh": "10s", "query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)" } } }, "inputs": { "input_1": { "type": "input.timerange", "title": "Select a time:", "options": { "token": "TimeRange", "defaultValue": "-24h,now" } } }, "layout": { "options": { "submitButton": false, "height": 1250, "display": "auto-scale", "width": 1200 }, "globalInputs": [ "input_1" ], "structure": [ { "item": "viz_chart1", "type": "block", "position": { "x": 250, "y": 80, "w": 680, "h": 530 } } ], "type": "absolute" }, "title": "Time Picker Input Example", "description": "Add a time range picker to modify a search time span." }
Add secondary data sources to your visualization | Add and format visualizations |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.2.2403 (latest FedRAMP release), 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 8.2.2112
Feedback submitted, thanks!