Mustache parameter syntax

important

Mustache parameter syntax is supported in the legacy SQL editor only. Databricks recommends using named parameter markers for new queries. If you copy a query using mustache syntax into a notebook, AI/BI dashboard dataset editor, or Genie space, you must convert it to named parameter markers before it will run.

In the legacy SQL editor, any string wrapped in double curly braces ({{ }}) is treated as a query parameter. A widget appears above the results pane where you set the parameter value.

Add a mustache parameter

1. Press Cmd + I. The parameter is inserted at the cursor position and the Add Parameter dialog appears.
2. Enter the Keyword, optionally change the Title, and select a Type.
3. Click Add Parameter.
4. Set the parameter value in the widget.
5. Click Apply Changes.
6. Click Save.

Alternatively, type {{ }} directly in the query and click the gear icon in the parameter widget to configure it.

To re-run the query with a different value, update the widget and click Apply Changes.

Edit, remove, and reorder parameters

Edit: Click the gear icon beside the parameter widget. To prevent users who don't own the query from changing the parameter value, click Show Results Only.

Remove: Delete the parameter marker from the query. The widget is removed automatically.

Reorder: Click and drag parameter widgets to the desired order.

Widget types

The following widget types are available:

Text

Takes a string as input. Backslash, single, and double quotation marks are escaped automatically. Databricks adds quotation marks around the value.

SQL

SELECT * FROM samples.tpch.customer WHERE c_name = {{ name_param }}

Number

Takes a number as input.

SQL

SELECT * FROM users WHERE age = {{ number_param }}

Date and Time

Parameterizes date and timestamp values. Three options are available:

Type	Precision
Date	Day
Date and Time	Minute
Date and Time (with seconds)	Second

All date and time values are passed as string literals and must be wrapped in single quotation marks in your query:

SQL

SELECT * FROM usage_logs WHERE date = '{{ date_param }}'

When you select a Range option, Databricks creates two parameters using .start and .end suffixes:

SQL

SELECT * FROM usage_logs
WHERE modified_time > '{{ date_range.start }}'
AND modified_time < '{{ date_range.end }}'

note

The Date Range widget returns correct results only for DATE-type columns. For timestamp columns, use a Date and Time Range widget.

Dynamic date values: Date widgets include a blue lightning bolt icon. Click it to select dynamic values such as today, yesterday, this week, last week, last month, or last year. These values update automatically.

important

Dynamic date values are not compatible with scheduled queries.

Dropdown List

Restricts input to a predefined static list. Supports both single-value and multi-value selection.

• Single value: Wrap the parameter in single quotation marks in the query.

• Multi-value: Enable Allow multiple values in the widget settings. Use the Quotation option to control whether values are wrapped in single quotes, double quotes, or none. Update your WHERE clause to use IN:

  SQL

  SELECT * FROM orders WHERE status IN ( {{ status_param }} )

  With double quotation marks selected, the query resolves to: WHERE status IN ("value1", "value2", "value3").

Dropdown List values are strings. To use dates or timestamps, enter them in the format your data source requires.

Query-Based Dropdown List

Populates dropdown choices from a saved query. Behaves like Dropdown List but the options are dynamic.

1. Under Type in the settings panel, select Query Based Dropdown list.
2. Click the Query field and select a saved query.

If the query returns more than one column, Databricks uses the first column. If the query returns columns named name and value, the widget displays the name column but passes the associated value to the query at runtime.

Example:

SQL

SELECT user_uuid AS 'value', username AS 'name' FROM users

value	name
1001	John Smith
1002	Jane Doe
1003	Bobby Tables

The value passed to the database at runtime is 1001, 1002, or 1003, not the display name.

note

Performance degrades if the source query returns a large number of records.

Use mustache parameters in legacy dashboards

Optionally, queries can use parameters or static values. When a visualization based on a parameterized query is added to a dashboard, you can configure each parameter to use one of three value sources:

• Widget parameter: Applies only to the single visualization it belongs to. The value selector appears inside the visualization panel.
• Dashboard parameter: Can apply to multiple visualizations across the dashboard. The value selector appears at the top of the dashboard. Added by default when you add a parameterized visualization to a dashboard.
• Static value: Replaces the parameter with a fixed value. The value selector is hidden, keeping the dashboard UI clean for parameters that don't need to change.

To access parameter mapping settings, click the kebab menu on a dashboard widget and select Change widget settings.

Dashboard parameter properties

Property	Description
Title	The display name shown beside the value selector. Defaults to the parameter keyword. Not shown for static parameters.
Keyword	The string literal for this parameter in the underlying query. Useful for debugging unexpected results.
Default Value	The value used when no other value is specified. To change it, run the query with the desired value and click Save.
Value Source	Controls where the parameter value comes from. Options: New dashboard parameter, Existing dashboard parameter, Widget parameter, Static value.