Databricks SQL dashboards

You can use SQL editor to build a Databricks SQL dashboard that combines visualizations and text boxes that provide context with your data.

View and organize dashboards

Two ways to view dashboards:

• View new dashboards in the workspace browser by clicking Workspace in the sidebar. These dashboards are viewable, by default, in the Home folder. Users can organize dashboards into folders in the workspace browser along with other Databricks objects. To view and organize currently existing dashboards, users (or admins) must migrate them into the workspace browser. For information about the workspace browser, including migration, see Workspace browser.

• All dashboards, regardless of creation time or migration status, can also be viewed by clicking the Dashboards in the sidebar.

By default, dashboards are sorted in reverse chronological order. Reorder the list by clicking the column headings.

Important

Starting on July 10, 2023, Databricks will force-migrate all Databricks SQL content (dashboards, queries, alerts) to the workspace browser. Visit My Dashboards and look for any un-migrated dashboards, which will have a checkbox on the lefthand side. When a box is checked, a Migrate button will appear that allows you to migrate multiple assets at a time. If no action is taken, your dashboards will be moved to your user folder. Admins should ensure that all objects without a valid active owner are updated to have one. Starting on September 10, 2023, we will delete all unmigrated objects without a valid owner.

Organize dashboards into folders in the workspace browser

Organize new and existing dashboards into folders in the workspace browser along with other Databricks objects. For more information, see Workspace browser.

Filter the list of saved dashboards

Filter the list of all dashboards by dashboards that you created (My Dashboards), by favorites, and by tags.

Create a dashboard

Follow these steps to create a new dashboard. To clone an existing dashboard, see Clone a dashboard.

1. Do one of the following:

   • Click New in the sidebar and select Dashboard.

   • Click Dashboards in the sidebar and click + Create Dashboard.

   • Click Workspace in the sidebar and click + Create Dashboard.

   • If you don’t want to start from an empty dashboard, you can create a quick dashboard:

     1. Click Data in the sidebar.

     2. Browse to the table, then in the Actions menu, click Create a quick dashboard.

     3. In the configuration page, select columns of interest and create a dashboard and supporting queries that provide some basic information using those columns and showcase dashboard-level parameters and other capabilities.

     4. Continue with the following steps to customize the dashboard.

2. Enter a name for the dashboard.

3. When you create a dashboard, you have the option to specify a warehouse to be used for manual refresh. If you do not select and save a warehouse to the dashboard, it will fall back to using the warehouse saved to individual queries.

Note

If you select and save a warehouse to the dashboard and then it is deleted or otherwise becomes unavailable, manual refresh will fail until a new one is assigned.

1. Add content to the dashboard by clicking Add and selecting the type of content to add:

   • Click Textbox to add commentary.

     Enter text. You can style the text boxes using Markdown. To include static images within text boxes on your dashboards, use Markdown image syntax:![alt-text](<image-url>).

   • Click Visualization to add a query visualization.

     1. Select a query. Search existing queries or pick a recent one from the pre-populated list. If a query was saved with the Limit 1000 setting, the query in the dashboard limits results to 1000 rows.

     2. In the Choose Visualization drop-down, select the visualization type.

        

2. Click Add to Dashboard.

3. Drag and drop content blocks on the dashboard.

4. Click Done Editing.

   

You can also create a dashboard with the Databricks Terraform provider and databricks_sql_dashboard. You can create a widget for a dashboard with databricks_sql_widget. You can create a sample dashboard with dbsql-nyc-taxi-trip-analysis.

Clone a dashboard

If you have the Can Run, Can Edit, and Can Manage permissions on a dashboard and each of its upstream queries, you can clone the dashboard and all upstream queries. You become the owner of the new dashboard and queries.

Important

Sharing settings, alerts, and subscriptions are not copied to the new dashboard.

To clone a dashboard:

1. Open the vertical ellipsis at the top-right of the dashboard and select Clone.

2. Enter a name for the new dashboard, then click Confirm.

Using query parameters in dashboards

Queries can optionally leverage parameters or static values. When a visualization based on a parameterized query is added to a dashboard, the visualization can either be configured to use a:

• Widget parameter

  Widget parameters are specific to a single visualization within a dashboard, appear within the visualization panel, and the parameter values specified apply only to the query underlying the visualization.

• Dashboard parameter

  Dashboard parameters can apply to multiple visualizations. When you add a visualization based on a parameterized query to a dashboard, by default the parameter will be added as a dashboard parameter. Dashboard parameters are configured for one or more visualizations within a dashboard and appear at the top of the dashboard. The parameter values specified for a dashboard parameter apply to visualizations reusing that particular dashboard parameter. A dashboard can have multiple dashboard parameters, each of which may apply to some visualizations and not to other visualizations.

• Static value

  Static values are used in lieu of a parameter that responds to changes. Static values allow you to hard code a value in place of a parameter and will make the parameter “disappear” from the dashboard or widget where it previously appeared.

When you add a visualization containing a parameterized query, you can choose the the title and the source for the parameter in the visualization query by clicking the appropriate pencil icon . You can also select the keyword and a default value. See Parameter properties.

After adding a visualization to a dashboard, you can access the parameter mapping interface by clicking the vertical ellipsis on the top right of a dashboard widget then clicking Change widget settings.

Parameter properties

The dashboard widget parameter properties are:

• Title: The display name that appears beside the value selector on your dashboard. It defaults to the title set in the query editor. To edit how it appears within the dashboard, click the pencil icon . Titles are not displayed for static dashboard parameters because the value selector is hidden. If you select Static value as your Value Source then the Title field is grayed out.

• Keyword: The string literal for this parameter in the underlying query. This is useful for debugging if your dashboard does not return expected results.

• Default Value: The value set for that parameter on dashboard load until another is selected and changes applied. To change this default, open the underlying query in the SQL editor, change the parameter to your desired value and click the Save button.

• Value Source: The source of the parameter value. Click the pencil icon to choose a source.

  • New dashboard parameter: Create a new dashboard-level parameter. This lets you set a parameter value in one place on your dashboard and map it to one or more visualizations. Note that parameters must have unique names within the dashboard.

  • Existing dashboard parameter: Map this visualization’s parameter to an existing dashboard parameter. You must specify which pre-existing dashboard parameter.

  • Widget parameter: Displays a value selector inside your dashboard widget. This is useful for one-off parameters that are not shared between widgets.

  • Static value: Choose a static value for the widget, regardless of the values used on other widgets. Statically mapped parameter values do not display a value selector anywhere on the dashboard which is more compact. This lets you take advantage of the flexibility of query parameters without cluttering the user interface on a dashboard when certain parameters are not expected to change frequently.

  

Remove content from a dashboard

1. Click the vertical ellipsis at the top-right of the widget and select Remove from Dashboard.

2. Click Delete.

Edit a dashboard

To open the dashboard for editing, open the vertical ellipsis at the top-right of the dashboard and select Edit.

While editing you can add and remove content, edit visualizations, and apply filters. To change the order in which parameters are shown, you can click and drag each parameter to the desired position.

Filter across multiple queries

To filter across multiple queries on a dashboard:

1. Go to your Databricks SQL dashboard.

2. In Edit mode, click Add, and then click Filter.

3. Select New dashboard filter and choose the queries and columns to filter. You can also choose to import filters from existing queries by selecting Existing query filters and choosing to import a filter from a SQL query editor. The queries you choose must belong to the same catalog and schema.

4. Click Save. This creates a filter that contains the union of all dropdown options.

Note

The queries you choose must belong to the same catalog and schema. Some old queries may not be compatible with filtering across multiple queries.

Edit a dashboard visualization

To edit a visualization on the dashboard while in edit mode, select the visualization you wish to edit and then click the vertical ellipsis at the top-right of the visualization. In the displayed list, select Edit visualization.

Add content to a dashboard

1. Open the dashboard for editing.

2. Click Add Textbox or Add Widget.

3. Click Add to Dashboard.

4. Click Done Editing.

You can also add a visualization to a dashboard in the SQL editor.

Remove content from a dashboard

1. Click the or hover over the object, click the vertical ellipsis at the top-right of the widget and select Remove from Dashboard.

2. Click Delete.

Dashboard filters

When queries have filters you must also apply filters at the dashboard level. Select the Use Dashboard Level Filters checkbox to apply the filter to all queries.

Customize dashboard colors

You can customize the dashboard color palette, including creating a color palette.

Create a color palette

To create a custom color palette for a dashboard:

1. Click at the top right, and click Edit.

2. Click Colors.

3. To import an existing color palette, click Import and select the palette. You can customize the imported palette.

4. To create a new palette, or to customize an imported palette, do the following:

   1. To add a new color, click Add.

   2. For a newly-added color or an existing color, specify the color by doing either of the following:

      • Click the square and select the new color by clicking it in the color selector or using the eyedropper.

      • Click the text field next to the square and enter a hexadecimal value.

5. Click Apply.

Stop using a custom color palette

To remove a custom color palette:

1. Click at the top right, and click Edit.

2. Click Colors.

3. Click Clear.

4. Click Apply.

Use a different color palatte for a visualization

By default, if a color palette has been applied in a dashboard, all visualizations will use that color palette. If you’d like to use different colors for a visualization, you can override this behavior:

1. Click for the visualization in the dashboard and click Edit.

2. Click the checkbox next to Retain colors specified on visualization.

3. Click OK.

Refresh a dashboard

Dashboards should load quickly because they fetch their data from a cache that renews whenever a query runs. But if you haven’t run the queries recently, your dashboard might be stale. It could even mix old data with new if some queries ran more recently than others. Verify when your visualizations were last refreshed.

Each time a dashboard is refreshed, either manually or on a schedule, all queries in the dashboard and all upstream queries, including those used by parameters, are refreshed. When an individual visualization is refreshed, all upstream queries, including those used by parameters, are refreshed.

Refresh behavior and execution context

When a dashboard is “Run as Owner” and a schedule is added, the owner’s credential is used for execution and anyone with at least “Can Run” sees the results of those refreshed queries.

When a dashboard is “Run as Viewer” and a schedule is added, the owner’s credential is used for execution but only the owner sees the results of the refreshed queries; all other viewers must manually refresh to see updated query results.

Manually refresh a dashboard

To force a refresh, click Refresh on the top right of the dashboard. This runs all the dashboard queries and updates its visualizations.

Automatically refresh a dashboard

A dashboard’s owner and users with the Can Edit permission can configure a dashboard to automatically refresh on a schedule. To automatically refresh a dashboard:

1. Click Schedule at the top right of the dashboard. The scheduling dialog appears.

   

2. In the Refresh every drop-down, select a period.

3. In the SQL Warehouse drop-down, optionally select a SQL warehouse to use for all the queries. If you don’t select a warehouse, the queries execute on the last used SQL warehouse.

Note

This warehouse can be different than the one used for manual refresh.

1. Next to Subscribers, optionally enter a list of email addresses to notify when the dashboard is automatically updated.

   Each email address you enter must be associated with a Databricks account or configured as a notification destination.

2. Click Save. The Schedule label changes to Scheduled.

Dashboard snapshot subscriptions

You can periodically export and email dashboard snapshots. Dashboard snapshots are taken from the default dashboard state, meaning that any interaction with the filters and visualizations are not included in the snapshot.

If you are the owner of a dashboard or if you have the Can Edit permission, you can create a refresh schedule and subscribe other users, who will receive email snapshots of the dashboard every time it’s refreshed.

Note

If you have the Can Edit permission, you are limited to subscribing users who already have access to the dashboard, or subscribing notification destinations that are already configured. If you have the Can Manage permission, you can subscribe any user with access to the workspace.

To add subscribers, enter one or more email addresses for dashboard users or notification destinations in the Subscribers field.

If you have the Can View or Can Edit permission for a dashboard, you can subscribe to existing refresh schedules. To subscribe, click the Subscribe button.

There is a 6 MB file size limit for email attachments. If a dashboard subscription email exceeds the 6 MB size limit, the email will omit the inline dashboard snapshot and include only a PDF of the dashboard snapshot.

If the PDF snapshot file exceeds 6 MB, the subscription email will omit the PDF and instead include a link to the refreshed dashboard. There will be a warning note in the email detailing the current dashboard size. (Users can test the PDF snapshot size by manually downloading a PDF of the dashboard.)

Temporarily pause scheduled dashboard updates

If a dashboard is configured for automatic updates, it has a Scheduled button at the top, rather than a Schedule button. You can temporarily pause dashboard updates and scheduled export to subscriptions. This is helpful to avoid sending updates while testing changes to the dashboard. To temporarily pause scheduled dashboard updates without modifying the list of subscribers:

1. Click Scheduled.

2. Click the Enabled toggle.

3. Click Save.

Stop automatically updating a dashboard

If a dashboard is configured for automatic updates, it has a Scheduled button at the top, rather than a Schedule button. To stop automatically updating the dashboard and remove its subscriptions:

1. Click Scheduled.

2. In the Refresh every drop-down, select Never.

3. Click Save. The Scheduled button label changes to Schedule.

Download as PDF

To download a dashboard as a PDF file, click the vertical ellipsis at the top-right of the dashboard and select Download as PDF.

Move a dashboard to Trash

To move a dashboard to Trash, click the vertical ellipsis at the top-right of the dashboard and select Move to Trash. Confirm by clicking Move to Trash.

Restore a dashboard from Trash

1. Click Dashboards in the sidebar.

2. Click .

3. Click a dashboard.

4. Click the vertical ellipsis at the top-right of the dashboard and select Restore.

Permanently delete a dashboard

1. In the All Dashboards list, click .

2. Click a dashboard.

3. Click the vertical ellipsis at the top-right of the dashboard and select Delete.

Open a query

To open the query displayed in a widget in the SQL editor, click the vertical ellipsis at the top-right of the widget and select View Query.

Configure dashboard permissions

To configure who can manage and run dashboards, see Dashboard access control.

Access admin view

A Databricks admin user has view access to all dashboards. In this view an admin can view and delete any dashboard. However, an admin can’t edit a dashboard if it is not shared with the admin.

To view all dashboards:

1. Click Dashboards in the sidebar.

2. Click Admin View on the right panel.

Transfer ownership of a dashboard

If a dashboard’s owner is removed from a workspace, the dashboard no longer has an owner, and only an admin user can manage the dashboard’s permissions. An admin user can transfer ownership of any dashboard, including one without an owner, to a different user. To transfer ownership by using the Databricks SQL UI:

1. Open the dashboard.

2. Click Share.

3. Click Assign new owner.

4. Select the new user you’d like to make the owner from the dropdown and click Confirm.

To transfer ownership by using the REST API, see Transfer ownership of a dashboard.

If the dashboard previously had an owner, that user no longer has the Can Manage permission on the dashboard. The user you gave the Can Manage permission is now the owner.