Use Lakeview dashboard parameters

Lakeview 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 Lakeview 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 Lakeview dashboard dataset. You can add parameters directly to the dataset queries in the Data tab.

Gif shows an example of the following steps.

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 Gear icon 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 Filter Icon Add a filter (field/parameter).

  2. Click add field icon 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

Lakeview 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.

Lakeview dashboard parameters vs. Databricks SQL query parameters

Lakeview dashboard parameters use the same syntax as named parameter markers. See Named parameter markers. Lakeview dashboards do not support Databricks SQL style parameters.