What you will be able to do
- Add a parameter to a dashboard dataset and configure it in the Parameter details dialog
- Test a parameterized dataset with default values and explain why that step matters
- Write multi-select and date range parameter queries that also handle All
- Connect a parameter to a filter widget and decide between a parameter and a field filter
1.Adding a parameter to a dashboard dataset
AI/BI dashboard parameters substitute values into a dataset's SQL at runtime. Because the value enters the query itself, data can be filtered before it is aggregated. Parameters are added to datasets on the Data tab, and you need at least CAN EDIT permission on the draft dashboard. Put your cursor where the value belongs and click Add parameter. This inserts a colon-prefixed marker with the default name parameter. You can also type the marker yourself, for example :segment.
Click the icon next to the parameter name to open the Parameter details dialog. Click elsewhere in the UI to close it.
| Field | What it controls |
|---|---|
| Keyword | The name used in the query; can only be changed by editing the query text |
| Display name | The name shown in the filter editor; defaults to the keyword |
| Type | String (default), Date, Date and Time, or Numeric (Decimal by default, or Integer) |
| Allow multiple selections | Lets users choose several values at runtime; may require a query change |
Checkpoint 1 of 7· Check yourself
You want to rename a dashboard parameter's keyword from parameter to region. Where do you do it?
The dialog shows the keyword but can't change it. Only editing the query text renames it. Display name changes only the label in the filter editor.
“This can only be changed by directly updating the text in the query.”Source: docs.databricks.com
Sources1
2.Testing with default values
To test a parameter, type a value in the text field under the parameter name and run the query. You get a preview of the results, and running the query also saves that value as the parameter's default. The default matters later: a filter widget uses the Data tab default unless the widget sets its own.
Testing is more than a courtesy. Databricks runs the dataset with its defaults to read the schema, and that schema populates the widget configuration editor. A query can work when a viewer picks a value but still fail with the defaults. The docs call out parameters in an IDENTIFIER clause as a typical case. Authors should therefore confirm on the dataset tab that the query succeeds with the defaults they selected.
Checkpoint 2 of 7· Check yourself
A dataset uses IDENTIFIER(:col). It works when viewers choose a column, but fails when run with the saved default. Why should the author still fix the default?
The widget configuration editor depends on the schema that Databricks reads from the dataset. If the default run fails, there is no schema to configure widgets with.
“Databricks queries the dataset schema to populate the widget configuration editor.”Source: docs.databricks.com
Checkpoint 3 of 7· Exam question
A dashboard author configures a parameter's type as "Date Range" so viewers can pick a start and end date for a shipment report. After saving, the author needs to reference the range inside the dataset's WHERE clause. Which pair of generated parameter names should the author use?
Correct answer: A — :ship_date.min and :ship_date.max
- A. Choosing the Date Range type automatically creates two bound parameters that carry `.min` and `.max` suffixes on the base keyword, and the WHERE clause is written as `date_col BETWEEN :ship_date.min AND :ship_date.max` to consume both bounds together.
- B. Underscore-suffixed start and end names look plausible but are not the naming convention the range-type parameter generator produces; the query editor would not recognize these as bound to the range widget.
- C. Array-index bracket notation is not how Databricks exposes the two bounds of a date range parameter, and this syntax would fail to parse as a valid named parameter reference in the query.
- D. The words "from" and "to" read naturally for a range but are not the suffixes the platform actually generates; using them leaves the query referencing parameters that were never created.
Sources1
3.Multi-select parameters
Turning on multiple selections changes what the parameter is: it becomes an array. The query and the setting have to agree. If you use ARRAY_CONTAINS without enabling multiple selections, you get an error. There is also an All case. When a viewer selects All, the parameter is NULL, so the documented pattern adds OR :parameter IS NULL to return every row. To set multi-value defaults, type a value in the field under the display name, select it, and then type the next one.
Checkpoint 4 of 7· Fill the gap
Which function completes this multi-select dashboard query?
SELECT
*
FROM
samples.tpch.lineitem
WHERE ? (:parameter, l_quantity) OR :parameter IS NULLarray_contains keeps rows whose l_quantity matches at least one selected value. The IS NULL branch returns all rows when All is selected.
Source: docs.databricks.comSources1
4.Date range parameters
Choose the Date Range or Date and Time Range type and Databricks creates two parameters with .min and .max suffixes. The suffixes go in the query, not in the dialog: when you enter the Keyword and Display name, leave .min and .max off. The query uses BETWEEN on the two ends and, like multi-select, adds an IS NULL branch so that All returns every row.
SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min AND :date_param.max
OR :date_param IS NULLCheckpoint 5 of 7· Put it in order
Put the steps for creating and testing a dashboard date range parameter in order
- 1.Insert a WHERE clause using BETWEEN :date_param.min AND :date_param.max OR :date_param IS NULL
- 2.Choose Date Range or Date and Time Range as the Type
- 3.Click Add parameter
- 4.Open the parameter details and enter the Keyword and Display name without .min or .max
- 5.Enter default date values and run the query to test it
The parameter and its type come first, then the query that uses .min and .max. The final run tests the query and saves the defaults.
“Enter the Keyword and Display name. Do not include .min or .max suffixes.”Source: docs.databricks.com
For defaults, the calendar icon offers presets such as last week or last month. For a rolling window, type an expression in the default value field instead. now-{n}d/d means n days back from today, rounded to the start of the day. A last-30-days default is .min = now-30d/d and .max = now/d.
Checkpoint 6 of 7· Exam question
A retail analyst enables "Allow multiple selections" on a `region` parameter so dashboard viewers can pick several regions at once, including an option to show every region when nothing is explicitly chosen. Which WHERE clause correctly implements this multi-select behavior?
Correct answer: A — WHERE array_contains(:region, region_col) OR :region IS NULL
- A. A multi-select parameter is passed to the query as an array, so the row's column must be tested with `array_contains(:parameter, column)`, and appending `OR :parameter IS NULL` restores every row when the viewer leaves the selection on the default all-values state.
- B. A plain equality comparison expects a single scalar value on the right side, but a multi-select parameter resolves to an array, so this comparison would raise a type mismatch rather than matching selected regions; it also compares the parameter to `NULL` with `=`, which always evaluates to unknown instead of triggering the intended all-rows fallback.
- C. The IN clause syntax does not automatically unpack an array-typed parameter the way `array_contains` does, so this form does not reliably test membership against a multi-select selection even though the null fallback is written correctly.
- D. Reversing the argument order passed to `array_contains` swaps the column and the array-valued parameter, which breaks the function's expected column-then-value-list semantics even though the null fallback clause itself is written correctly.
Sources1
5.Connecting parameters to filter widgets
A parameter becomes interactive once you connect it to a filter widget. Click Add a filter (field/parameter), place the widget, choose a filter type, and under Parameters pick the dataset's parameter. Parameter filters can be single value, multiple values, date picker or date range. When a viewer picks a value, the associated query reruns.
A plain single-value filter makes viewers type a value, matching its case and spelling exactly. The fix is a query-based parameter. Create a second dataset such as SELECT DISTINCT c_mktsegment from the customer table, then add its column under the widget's Fields. The widget then shows a drop-down list of real values and passes the chosen one to the parameter.
| Consideration | Field filter | Parameter |
|---|---|---|
| How it applies | Applied to resolved dataset results | Substituted into the dataset query at runtime |
| Performance | Typically faster; small datasets filtered in the browser | Query reruns whenever the value changes |
| Versatility | Can't be used in subqueries or custom conditional logic | Can be used in subqueries, conditional logic, or to change query structure |
Checkpoint 7 of 7· Check yourself
A dataset joins a large fact table to a dimension, and you want the viewer's region choice to cut rows before the join. Which should you use?
A field filter wraps the SQL in a CTE and applies at the end. A parameter can sit anywhere in the query, including before the join, so less data goes into the join.
“With parameters, you can place filter conditions anywhere in the query, such as before a join rather than after it.”Source: docs.databricks.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Writing ARRAY_CONTAINS in the query is enough to make a dashboard parameter multi-select.Why is that wrong?
The Allow multiple selections setting must also be on, so that the parameter is inserted as an array. Without it, the query errors.
Covered in Multi-select parameters
2.A date range parameter's Keyword should be entered as date_param.min and date_param.max.Why is that wrong?
Enter the base keyword only. The .min and .max suffixes are used in the query, not in the Keyword field.
Covered in Date range parameters
3.If a parameterized dataset works when viewers choose a value, a failing default doesn't matter.Why is that wrong?
Databricks uses the default values to read the dataset schema for the widget editor. IDENTIFIER queries can fail with the defaults and still work at runtime.
Covered in Testing with default values
Practise it for real
Build a dashboard whose bar chart is filtered by a market-segment parameter chosen from a drop-down list
1.Create a new dashboard, open the Data tab, click Add SQL dataset, run SELECT * FROM samples.tpch.customer and rename the dataset Marketing segment
Why: Parameters live in dataset queries, which you edit on the Data tab
You should see: Customer rows are returned and the dataset is autosaved
2.Append WHERE c_mktsegment = :segment, type BUILDING in the text field below the query, and rerun
Why: Running with a value tests the parameter and saves BUILDING as its default
You should see: A segment field appears under the query and only BUILDING rows are returned
3.On the canvas, add a Bar visualization with c_nationkey (Categorical) on the X-axis and SUM of c_acctbal on the Y-axis
Why: The chart shows the parameter's effect
You should see: The chart includes only BUILDING records
4.Click Add a filter (field/parameter), choose Single value, title it Segment, and under Parameters choose segment from Marketing segment
Why: Connecting the parameter to a filter widget lets viewers change it
You should see: The widget shows the default value BUILDING
5.Add a dataset SELECT DISTINCT c_mktsegment FROM samples.tpch.customer named Segment choice, then add its c_mktsegment column under the widget's Fields
Why: A query-based list means viewers don't have to type the value with the exact case and spelling
You should see: Clicking the filter shows a drop-down list of the five market segments
Stuck? Get a nudge
If the filter widget doesn't list your parameter, go back to the Data tab and check that the dataset runs successfully with its default value.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“You must have at least CAN EDIT permissions on the draft dashboard to add a parameter to a dashboard dataset.”
↩︎ Adding a parameter to a dashboard dataset“Supported types include String, Date, Date and Time, Numeric. The default type is String.”
↩︎ Adding a parameter to a dashboard dataset“Running the query also saves the default value.”
↩︎ Testing with default values“the default value from the Data tab is used unless the widget specifies a different default”
↩︎ Testing with default values“If "All" is selected, the parameter is NULL and all rows are returned (no filtering is applied).”
↩︎ Multi-select parameters“For example, to configure a default range of the last 30 days, set the .min value to now-30d/d and the .max value to now/d.”
↩︎ Date range parameters“If the ARRAY_CONTAINS function is used without enabling multiple selections, an error occurs.”
↩︎ Exam trap 1“Enter the Keyword and Display name. Do not include .min or .max suffixes.”
↩︎ Exam trap 2“particularly with parameterized queries that use the IDENTIFIER clause, the dataset query can fail to run with the default parameter values”
↩︎ Exam trap 3“This can only be changed by directly updating the text in the query.”
↩︎ Checkpoint“Databricks queries the dataset schema to populate the widget configuration editor.”
↩︎ Checkpoint“Queries that allow multiple selections must include an ARRAY_CONTAINS function in the query.”
↩︎ Prediction“Enter the Keyword and Display name. Do not include .min or .max suffixes.”
↩︎ Checkpoint - 2.
“Parameters substitute values at runtime and always require the associated query to rerun.”
↩︎ Connecting parameters to filter widgets“With parameters, you can place filter conditions anywhere in the query, such as before a join rather than after it.”
↩︎ Checkpoint - 3.
“It also requires that users match the case and spelling when entering the desired parameter value.”
↩︎ Connecting parameters to filter widgets