Runtime parameters can be used to supply query templates with tokens that are replaced during query execution. The tokens can be values from:
- User input from dashboard filters
- User input from filters
- Hidden user-level filters based on the user configuration
- Hidden Content filters (embedding scenarios)
Tokens can be applied at the query level or at the datasource level. Runtime parameters are only applicable for Direct queries. In addition to queries, Runtime parameters can also be applied at the datasource level (not too common).
High-Level Steps
- Define the token(s) in the Query.
- Specify an optional label if you'd like the user to input the values.
- When a widget associated with this query is added to the dashboard, the filter will include the Label associated with the token (or applied automatically if hidden).
- For User input fields, if you'd like a picklist to be shown, change the filter to get suggestions from another dataset that has a list of values.
There are two ways to create Runtime parameters:
- Token Editor in the Query Editor mode
- Using the Visual Builder
Query Editor
You can write Runtime Parameters into the query directly using Query Parameters Format or use the visual Token editor:
Click on the {:} Token button to create the runtime query. Click on the Insert Token button to add the token to your editor where your current cursor is.
The token modes can be one of the following modes:
Single Value
In this case, the token is a single value passed in. Define the following to insert the token:
-
Parameter Name: An identifier (without spaces).
-
Default Value (Optional): A default value to pass into the runtime parameter if the value is empty. Leave it empty if you do not wish to set a default.
-
Label (Optional): Enter the name you want the runtime filter to be displayed as in the filter menu at the dashboard or widget level.
List
In this case, multiple values are handled in the filter by adding Quote and Separator. Depending on your datasource and type, you will need to insert quotation marks and a separator. For example, for filter values of A and B selected by the user, if the Quote is a double quote and the Separator is a comma, the translation will occur as "A","B"
Date
Formats the date selected by the user from the filter to a date into the query, using the format required in your use case. For example, if the selected value is today, then today's date will be formatted into the query that you have specified.
Date Range
Formats a Date Range selected by the user. Use the same token label for the start and end date.
For example, the user selects a date range from the filter. To translate that date into your query, you can create the token where the condition for the date greater than equals to the start date (set that as the From), and the date less than equals to the end date (set that as the To).
Cloud 9QL
Use the {:} Token button to write the Cloud9QL syntax. Click on the Insert Token button to add the token to your editor where your current cursor is.
URL Parameters
Use the {:} Token button to write the URL Parameters. Click on the Insert Token button to add the token to your editor where your current cursor is.
Note: Limited to REST API datasource only
Visual Builder
Use the visual builder and create the Runtime Query Parameter via Filter functions in a no-code environment.
Preview Results
You can preview the configuration for the filter by clicking on the Preview button and selecting the value (if the default is not configured).
Note: If the default value is already selected, then the same will become automatically available for you while running the preview.
Once saved, you can add the runtime Query into the dashboard.