Use dashboard parameters

Dashboard parameters are one way to make dashboards interactive, enabling viewers to use single-value selectors and date pickers to input specific values into dataset queries at runtime. For example, parameters can filter data based on criteria like dates and product categories before it’s aggregated in a SQL query, allowing for more efficient querying and precise analysis.

Parameters are added to datasets and connected to one or more widgets on the canvas of a dashboard by a dashboard author or editor. Dashboard viewers interact with the dashboard data by selecting values in filter widgets at runtime. This reruns the associated queries and presents visualizations built on the filtered data.

Parameters directly modify the query, which can be powerful. Dataset filters can also offer dashboard interactivity, more features, and better performance with large datasets than parameters. See Filters.

Add a parameter

You must have at least Can Edit permissions on the draft dashboard to add a parameter to a dashboard dataset. You can add parameters directly to the dataset queries in the Data tab.

To add a parameter to a query:

1. Place your cursor where you want to place the parameter in your query.

2. Click Add parameter to insert a new parameter.

   This creates a new parameter with the default name parameter. To change the default name, replace it in the query editor. You can also add parameters by typing this syntax in the query editor.

Edit a parameter

To edit a parameter:

1. Click next to the parameter name. A Parameter details dialog appears.

   The dialog includes the following configuration options:

   • Keyword: The keyword that represents the parameter in the query. This can only be changed by directly updating the text in the query.

   • Display name: The name in the filter editor. By default, the title is the same as the keyword.

   • Type: Supported types include String, Date, Date and Time, Numeric.

     • The default type is String.

     • The Numeric datatype allows you to specify between Decimal and Integer. The default numeric type is Decimal.

2. Click another part of the UI to close the dialog.

Remove a parameter

To remove a parameter, delete it from your query.

Use a parameter on the dashboard canvas

To add a parameter to your dashboard:

1. Click Add a filter (field/parameter).

2. Click next to Parameters in the configuration panel.

3. Click the parameter name you want the viewer to use with this widget.

Include parameters in the URL

Parameter settings are stored in the URL, allowing users to bookmark it to maintain their dashboard’s state, including pre-set filters and parameters, or to share it with others for consistent application of the same filters and parameters.

Parameter syntax examples

Usage	Example use case	Dashboard parameter syntax
Insert a date	Include only records before a specific date	WHERE date_field < :date_param
Insert a number	Include only prices below a specific price	WHERE price < :max_price
Insert a table name	Change a table used in a query	SELECT * FROM IDENTIFIER(:param)
Insert other database objects	Change the catalog, schema, and table used in a query	SELECT * FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)
Concatenate multiple parameters	Combine two parameters with brackets to create formatted phone numbers	format_string('(%d) %d', :area_code, :phone_number) (1)

(1) Values are inserted using the format_string function. See format_string function.

Important

Enabling dashboard viewers to access data through parameter selections, like table or catalog names, could lead to accidental exposure of sensitive information. If you’re publishing a dashboard with these options, Databricks recommends not embedding credentials in the published dashboard.

Dashboard parameters vs. Databricks SQL query parameters

Dashboard parameters use the same syntax as named parameter markers. See Named parameter markers. Dashboards do not support Databricks SQL style parameters.