Dashboards

You can use dashboards to build data visualizations and share informative data insights with your team. AI/BI dashboards feature AI-assisted authoring, an enhanced visualization library, and a streamlined configuration experience so that you can quickly transform data into sharable insights.

Note

Dashboards (formerly Lakeview dashboards) are now generally available.

Dashboards are not available in Azure Government regions. Use legacy dashboards.

• Original Databricks SQL dashboards are now called legacy dashboards. They will continue to be supported and updated with critical bug fixes, but new functionality will be limited. You can continue to use legacy dashboards for both authoring and consumption.
• Convert legacy dashboards using the migration tool or REST API. See Clone a legacy dashboard to a Lakeview dashboard for instructions on using the built-in migration tool. See Dashboard tutorials for tutorials on creating and managing dashboards using the REST API.

AI/BI dashboards have the following components:

• Data: The Data tab allows users to define datasets for use in the dashboard. Datasets are bundled with dashboards when sharing, importing, or exporting them using the UI or API.
• Canvas: The Canvas tab allows users to create visualizations and construct their dashboards. The canvas holds widgets that can be configured to display visualizations, filters, text, or images.

Note

You can define up to 100 datasets per dashboard. The Canvas can contain up to 100 widgets per dashboard.

View and organize dashboards

You can access dashboards from the workspace browser along with other Azure Databricks objects.

• Click Workspace in the sidebar to view dashboards from the workspace browser. Dashboards are stored in the /Workspace/Users/<username> directory by default. Users can organize dashboards into folders in the workspace browser along with other Azure Databricks objects. See Workspace browser.

• To view the dashboard listing page, click Dashboards in the sidebar.

  By default, the dashboard listing page shows dashboards that you have access to sorted in reverse chronological order. You can filter the list by entering a title into the search bar, filter by last modified within a time period, or filter by owner.

• Click a dashboard title to open it. If the dashboard has been published before, the published version opens. Otherwise, the draft dashboard opens.

Create a new dashboard

To create a new dashboard from the dashboard listing page, click Create near the upper-right corner of the page.

Define your datasets

Use the Data tab to define the underlying datasets for your dashboard.

You can define datasets as any of the following:

• A new query against one or more tables or views.
• An existing Unity Catalog table or view.

You can define datasets on any type of table or view. You can define multiple datasets by writing additional queries or selecting additional tables or views. After defining a dataset, you can use the kebab menu to the right of the dataset name to rename, clone, or delete it. You can also download the dataset as a CSV, TSV, or Excel file.

Limit data access with SQL

All the data in a dashboard dataset can be accessible to dashboard viewers, even if it’s not displayed in a visualization. To prevent sensitive data from being sent to the browser, limit the columns specified in the SQL query that defines the dataset. For example, rather than selecting all columns from a table, choose only the specific columns needed for the visualizations in your SQL statement rather than table configuration.

Add or remove visualizations, text, and filter widgets on the canvas

Use the Canvas tab to construct your dashboard. Use the toolbar at the bottom of the canvas to add widgets such as visualizations, text boxes, and filters.

Visualizations

Create a visualization by adding a visualization widget to the canvas. Supported visualizations include area, bar, combo, counter, heatmap, histogram, line, pie, pivot, scatter, and table chart types.

Note

Queries used by visualizations do not always correspond precisely to the dataset. For example, if you apply aggregations to a visualization, the visualization shows the aggregated values.

To create a visualization, use one of the following methods:

• AI-assisted visualizations: Describe the chart you want to see in natural language and let the Databricks Assistant generate a chart. After it is created, you can modify the generated chart using the configuration panel. You cannot use Assistant to create table or pivot table chart types.
• Use the configuration panel: Apply additional aggregations or time bins in the visualization configuration without modifying the dataset directly. You can choose a dataset, x-axis values, y-axis values, and colors. See Dashboard visualization types for configuration details and examples of each supported visualization type. See Table options to learn how to control data presentation in table visualizations.

Note

When you apply temporal transformations in the visualization configuration, the date shown in the visualization represents the start of that period.

Text widgets

Markdown is a markup language for formatting text in a plain text editor. You can use markdown in text widgets to format text, insert links, and add images to your dashboard.

• To add a static image in a text widget, add markdown image syntax with a desired description and URL: ![description](URL) from a publicly available URL. For example, the following markdown will insert an image of the Databricks logo: ![The Databricks Logo](https://upload.wikimedia.org/wikipedia/commons/6/63/Databricks_Logo.png). To resize the image, resize the widget dimensions.
• To add an image from DBFS, add markdown image syntax with a desired description and FileStore path: ![description](files/path_to_dbfs_image). To resize the image, resize the widget dimensions. For more information on DBFS, see What is DBFS?.

For more information on markdown syntax, see this guide.

Filters

Filters are widgets that allow dashboard viewers to narrow down results by filtering on specific fields or setting dataset parameters. They function in the same way as slicers in other BI tools, allowing dashboard viewers to manipulate and refine the data presented in visualizations. Each filter widget can be configured to filter on dataset fields or to assign values to predefined parameters in a dataset query. Filters and parameters can be combined in a single widget when using query-based parameters. See Use query-based parameters to learn how to apply a query-based parameter.

Filter on fields

Dashboards support the following filter types for filtering on a field:

• Single value
• Multiple values
• Date picker
• Date range picker
• Text entry
• Range slider

Filters can be applied to fields of one or more datasets. To connect a filter to fields from more than one dataset, add multiple Fields, up to one per dataset. The filter applies to all visualizations built on the selected datasets. Filter selection cascades across all other filters.

Dashboard filters always apply to the entire dataset. If the dataset is small, the dashboard filter is applied directly in the browser to improve performance. If the dataset is larger, the filter is added to the query that is run in the SQL warehouse.

Filter on parameters

If a filter is connected to a parameter, it runs a query against the SQL warehouse, regardless of the dataset size.

Dashboards support the following filter types for filtering on a parameter:

• Single value
• Date picker

You can set parameter values to accept one of the following data types:

• String
• Date
• Date and Time
• Decimal
• Integer

See What are dashboard parameters?.

Note

Using parameters to specify date ranges is unsupported. To specify a date range, apply filters on the fields that include the start and end dates of the desired range.

Copy widgets

Use keyboard shortcuts to copy a selected widget and paste it back on the canvas. After you create a new widget, you can edit it as you would any other widget.

To clone a widget on your draft dashboard canvas, complete the following steps:

• Right-click on a widget.
• Click Clone.

A clone of your widget appears below the original.

Remove widgets

Delete widgets by selecting a widget and pressing the delete key on your keyboard. Or, right-click on the widget. Then, click Delete.

Download results

You can download datasets as CSV, TSV, or Excel files. You can download visualizations on the canvas as PNG files.

• To open download options from the Canvas tab, click the kebab menu in the upper-right corner of the widget.
• To open download options from a Data tab, click the kebab menu to the right of the dataset.

You can download up to approximately 1GB of results data in CSV and TSV format and up to 100,000 rows to an Excel file. The final file download size might be slightly more or less than 1GB, as the 1GB limit is applied to an earlier step than the final file download.

Draft and collaborate on a dashboard

New dashboards begin as a draft. You can share the draft with other users in your workspace to collaborate. Draft dashboards cannot be shared with users outside of the workspace. All users use their own credentials to interact with the data and visualizations in dashboard drafts.

For more on permission levels, see Dashboard ACLs.

Publish a dashboard

Publish a dashboard to create a clean copy of the current draft. You must have at least CAN EDIT permissions to publish a dashboard.

After you publish a dashboard, the published version remains intact until you publish again, even if you make changes to the draft. You can make modifications and improvements to the draft version without affecting the published copy. Any registered user with access to the published dashboard can continue to view the published version. The published version continues to be emailed to subscribers, if any exist.

When you publish a dashboard, you can choose to embed your credentials or not.

• Embed credentials: All viewers of a published dashboard can run queries using your credentials for data and compute. This allows users to see the dashboard even if they don’t have access to the originating workspace, underlying data, or SQL warehouse. This might expose data to users who have not been granted direct access to it. This is the default option.
• Don’t embed credentials: All viewers of the published dashboard run queries using their own data and compute credentials. Viewers need access to the workspace, the attached SQL warehouse, and the associated data to view results in the dashboard.

See Share a published dashboard for recommendations on which setting to choose.

To publish a dashboard, complete the following steps:

1. Open a dashboard. If the dashboard has been published previously, the published version opens. If necessary, use the switcher at the top of the page to see the current draft version.
2. Click Publish. The Publish dialog appears.
3. Choose the credentials to use for the published dashboard. You can choose to embed your credentials or not.
4. Click Publish. If your dashboard is being published for the first time, a Sharing dialog opens and prompts you to share the published dashboard. See Share a dashboard for details and recommendations on sharing.

To access the published dashboard, click Published in the drop-down menu near the top of the dashboard.

Schedule dashboards for periodic updates

You can set up scheduled updates to automatically refresh your dashboard and optionally send emails with a PDF of the latest dashboard to users who are subscribed to the schedule.

Users with at least Can Edit permissions can create a schedule so published dashboards with embedded credentials run periodically. Each dashboard can have up to ten schedules.

For each scheduled dashboard update, the following occurs:

• All SQL logic that defines datasets runs on the designated time interval.
• Results populate the query result cache and help to improve initial dashboard load time.

To create a schedule:

1. Click Schedule in the upper-right corner of the dashboard. The Add Schedule dialog appears.

   

2. Use the drop-down selectors to specify the frequency and time zone. Optionally, select the Show cron syntax checkbox to edit the schedule in Quartz Cron Syntax.

3. Click Create. The Schedules dialog appears and shows the schedule you created. If other schedules exist for this dashboard, the dialog also shows those.

4. Optionally, click Subscribe to add yourself as a subscriber and receive an email with a PDF snapshot of the dashboard after a scheduled run completes.

Note

If a schedule has already been created for this dashboard, the button in the upper-right corner says Subscribe. You can use the previously described workflow to add a schedule.

Manage subscriptions

Schedule subscribers receive an email with a PDF snapshot of the current dashboard each time the schedule runs. Eligible subscribers include workspace users and email notification destinations.

Note

If you cannot add email subscribers, your workspace admin may have turned off email notifications for your workspace. See Dashboard administration guide.

Workspace admins must define email notification destinations before they can be selected as subscribers. See Manage notification destinations. Account users, distribution lists, and users outside of the account (like users at partner or client organizations) can all be configured as email notification destinations and subscribed. However, they can’t be subscribed directly.

Important

Subscription lists can contain up to 100 subscribers. An email notification destination counts as one subscriber regardless of the number of emails it sends.

You can add and remove other subscribers to receive updates if you have at least Can Edit privileges on the dashboard. You can add and remove yourself as a subscriber to an existing schedule if you have at least Can View privileges on the dashboard.

• To subscribe other users:

  1. Click Subscribe in the upper-right corner of the dashboard. The Schedules dialog appears.
  2. Identify the schedule that you want to add subscribers to. Click the to the right of that schedule. Then, click Edit.

  Note

  You can also use this context menu to pause or delete a schedule.

  If you have Can View access to a dashboard that has an assigned schedule, you can subscribe yourself to receive updates each time a scheduled run occurs.

• To subscribe yourself to an existing schedule:

  1. Click the Subscribe button near the upper-right corner of the dashboard. The Schedules dialog shows all schedules for the dashboard.
  2. Click Subscribe to the right of the schedule you choose.

  If you cannot add yourself as a subscriber, check the following reasons:

  • A workspace admin has turned off the Enable dashboard subscriptions option for the workspace.

    This setting supersedes all others. If the workspace admin has turned this setting off, dashboard editors can still assign a schedule, but no subscribers can be assigned.

  • The dashboard is not shared with embedded credentials.

    Dashboards shared without embedded credentials cannot be assigned a schedule, so they cannot be assigned subscribers.

  • You do not have permission to access the workspace.

    Account users can only be added as subscribers as an email notification destination. There is no Subscribe button on the dashboard for account users.

  • No schedules have been defined.

    For dashboards without a defined schedule, workspace users with Can View or Can Run access to a dashboard cannot interact with the Subscribe button.

Unsubscribe from email updates

Subscribers can choose to stop receiving emails by unsubscribing from the schedule.

• To unsubscribe using the dashboard UI:

  1. Click the Subscribe button near the upper-right corner of the dashboard. The Schedules dialog shows all schedules for the dashboard.
  2. Click Subscribed to unsubscribe. The button text changes to Subscribe.

  

• Use the Unsubscribe link in the email footer to unsubscribe from scheduled updates.

Note

When a user who is included in a larger distribution list set up for email notifications chooses to unsubscribe using the link in the email footer, the action unsubscribes the entire distribution list. The group as a whole is removed from the subscription and will not receive future PDF snapshot updates.

Dashboard size limits for subscriptions

Dashboard subscription emails include the following base64 encoded files:

• PDF: A PDF file that includes the full dashboard.
• DesktopImage: An image file optimized for viewing on desktop computers.

A maximum limit of 9MB is imposed on the combined size of the two files. The following descriptions outline the expected behavior when the combined file size exceeds the limit:

• If the PDF file is greater than 9MB: The subscription email does not include the PDF attachment or any images. It includes a note that says the dashboard has exceeded the size limit and shows the actual file size of the current dashboard.
• If the combined file size is greater than 9MB: Only the PDF is attached to the email. The inline message includes a link to the dashboard but no image.

Export, import, or replace a dashboard

You can export and import dashboards as files to facilitate the sharing of editable dashboards across different workspaces. To transfer a dashboard to a different workspace, export it as a file and then import it into the new workspace. You can also replace dashboard files in place. That means that when you edit a dashboard file directly, you can upload that file to the original workspace and overwrite the existing file while maintaining existing sharing settings.

The following steps explain how to export and import dashboards in the UI. You can also use the Databricks API to import and export dashboards programmatically. See POST /api/2.0/workspace/import.

Export a dashboard file

• From a draft dashboard, click the kebab menu at the screen’s upper-right corner, then click Export dashboard.
• Confirm or cancel the action using the Export dashboard dialog. When the export succeeds, a .lvdash.json file is saved to your web browser’s default download directory.

Import a dashboard file

• From the Dashboards listing page, click > Import dashboard from file.
• Click Choose file to open your local file dialog, then select the .lvdash.json file you want to import.
• Click Import dashboard to confirm and create the dashboard.

The imported dashboard is saved to your user folder. If an imported dashboard with the same name already exists in that location, the conflict is automatically resolved by appending a number in parentheses to create a unique name.

Replace a dashboard from a file

• From a draft dashboard, click the kebab menu in the screen’s upper-right corner, then click Replace dashboard.
• Click Choose file to open the file dialog and select the .lvdash.json file to import.
• Click Overwrite to overwrite the existing dashboard.

Managing dashboards with the REST API

See Use Azure Databricks APIs to manage dashboards for tutorials that demonstrate how to use Azure Databricks REST APIs to manage dashboards. The included tutorials explain how to convert legacy dashboards into Lakeview dashboards, as well as how to create, manage, and share them.