9.1 Dashboard Parameters & Interactive Filtering

Databricks AI/BI Dashboards (built on Lakeview technology) represent a major evolution in how data teams build interactive data applications on the Databricks Data Intelligence Platform. Unlike legacy Redash or Databricks SQL dashboards, AI/BI Dashboards use a decoupled runtime architecture where visual components interact seamlessly with underlying Databricks SQL Warehouses. A central capability enabling rich user interaction is parameterization—allowing consumers to dynamically slice, dice, and filter dataset results without writing SQL code or requesting custom dashboard builds from data analysts.

Parameter Architecture & SQL Syntax

In Databricks AI/BI Dashboards, parameters are named variables declared within a dataset's SQL query using colon syntax (:parameter_name). When a dashboard viewer selects a value from a filter widget on the canvas, the AI/BI engine substitutes that value into the designated parameter placeholder prior to sending the query to the active SQL Warehouse for execution.

Declaring Parameters in SQL Datasets

Parameters can be placed in any valid SQL clause, including WHERE, HAVING, CASE statements, and join conditions. The following SQL dataset query illustrates single-value text parameters, date range parameters, and numeric threshold parameters:

SELECT 
    o.order_id,
    o.customer_id,
    c.customer_segment,
    o.order_date,
    o.shipping_region,
    o.total_amount,
    o.discount_amount
FROM main.sales_gold.fact_orders o
JOIN main.sales_gold.dim_customers c 
    ON o.customer_id = c.customer_id
WHERE o.order_date BETWEEN :start_date AND :end_date
  AND (:region = 'All' OR o.shipping_region = :region)
  AND o.total_amount >= :min_order_value;

When authoring this query in the AI/BI Dashboard SQL editor, Databricks automatically parses :start_date, :end_date, :region, and :min_order_value. The developer can then map these dataset parameters to canvas filter controls.

Canvas Filter Types & Binding Mechanics

AI/BI Dashboards support four primary parameter widget types on the visual canvas:

1. Text Inputs: Single-line text boxes for entering exact strings or wildcard search terms.
2. Number Inputs: Numeric fields for threshold filtering, percentiles, or top-N limits.
3. Date and Date Range Pickers: Calendar widgets allowing selection of specific dates, relative ranges (e.g., "Last 30 Days"), or custom start/end date pairs.
4. Dropdown Selectors: Single-select or multi-select dropdown menus displaying lists of predefined or dynamically generated values.

Global vs. Local Parameter Binding

A critical advantage of AI/BI Dashboards is multi-dataset parameter binding. A single canvas control—such as a Date Range picker—can be bound to :start_date and :end_date parameters across ten distinct dataset queries powering different widgets on the same canvas. When the user updates the date range picker, all ten queries execute concurrently with the updated date boundary values.

Field Filters vs. Parameter Filters

Databricks AI/BI Dashboards offer two distinct modes for canvas filtering: Field Filters and Parameter Filters. Understanding the operational differences between these two approaches is essential for both developer efficiency and query performance.

Cross-Filtering & Canvas Interactions

In addition to explicit parameter widgets, AI/BI Dashboards feature native cross-filtering. When cross-filtering is enabled on a canvas widget (such as a bar chart displaying revenue by region), clicking on a specific bar (e.g., "EMEA") automatically applies an interactive filter across all other charts on the dashboard that share the same underlying dataset or join key.

Cross-Filtering Execution Dynamics

• Client-Side Slicing: If the underlying dataset is already loaded in memory, cross-filtering applies instantly in the browser without issuing a new SQL Warehouse query.
• Server-Side Re-execution: If the cross-filtered selection requires data outside the loaded result set, the AI/BI engine issues a targeted subquery to the SQL Warehouse.
• Combined Filtering: Cross-filter selections operate as an AND condition alongside active canvas parameter widgets.

Developers can enable or disable cross-filtering independently on each visual widget via the widget setting panel. Disabling cross-filtering is recommended for reference charts (such as overall target benchmark lines) that should remain fixed regardless of user interactions elsewhere on the canvas.

Dynamic Dropdowns & Performance Best Practices

Dropdown filter parameters can be populated statically (a hardcoded list of values) or dynamically (driven by a SQL query). Dynamic dropdowns ensure filter options reflect current database states, such as displaying only regions that currently have active orders in the database.

Dynamic Dropdown Query Guidelines

To ensure dynamic dropdowns do not introduce performance bottlenecks:

1. Keep Queries Light: Dynamic dropdown queries should query small dimension tables or materialized views rather than scanning large fact tables.
2. Cardinality Ceilings: Databricks limits dynamic dropdown queries to 100,000 distinct values. Attempting to load high-cardinality fields (such as individual UUIDs or transaction timestamps) will cause truncation and degrade filter widget responsiveness.
3. Use Explicit Caching: Dynamic dropdown queries benefit significantly from SQL Warehouse result caching.

-- Optimal dynamic dropdown query targeting a small dimension table
SELECT DISTINCT region_name 
FROM main.sales_gold.dim_region 
WHERE is_active = true 
ORDER BY region_name;

URL Parameter Passing

Published AI/BI Dashboards support URL query parameters. This allows analysts to pre-filter dashboards when sharing links via email or embedding them in external tools. URL parameter syntax follows the format ?p_parameter_name=value. For example: https://<databricks-instance>/dashboards/v2/db-12345?p_region=EMEA&p_min_order_value=1000. Passing parameters via URL immediately applies the specified values upon page load, bypassing saved dashboard defaults for that session.