Dashboards

You can use dashboards to build data visualizations and share informative data insights with your team. The latest version of dashboards features 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.

• 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 Use Databricks APIs to manage dashboards for tutorials on creating and managing dashboards using the REST API.

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.

Note

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

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.

Note

See Clone a legacy dashboard to a Lakeview dashboard to create a new dashboard from an existing legacy dashboard. To migrate an individual Databricks SQL query to a new dashboard, use the + Create from SQL option in the Data tab of your dashboard. Copy and paste the Databricks SQL query text in the editor.

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.

Dataset optimizations

Dashboard datasets include the following performance optimizations:

• If the dataset result size is small (less than 64K rows), the dataset result is pulled to the client, and visualization-specific filtering and aggregation is performed on the client. Filtering and aggregating data for small datasets is very fast, and ensuring that your dataset is small can help you optimize dashboard performance. With small datasets, only the dataset query appears in the query history.

• If the dataset result size is large (>= 64K rows), the dataset query text is wrapped in a SQL WITH clause, and the visualization-specific filtering and aggregation is performed in a query on the backend rather than in the client. With large datasets, the visualization query appears in the query history.

• For visualization queries sent to the backend, separate visualization queries against the same dataset that share the same GROUP BY clauses and filter predicates are combined into a single query for execution. In this case, users might see one combined query in the query history that is fetching results for multiple visualizations.

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.

• Use the Databricks Assistant: Create visualizations by describing the chart you want to see in natural language and let the 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 in the configuration panel. See Dashboard visualization types for configuration details and examples of each supported visualization type. See Table options to learn how you can control data presentation in table visualizations.

Note

Visualization widgets remain blank until you describe the desired chart, or choose configuration settings to define the dataset, chart type, and values that you want to represent.

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 the Databricks File System (DBFS)?.

For more information on markdown syntax, see this guide.

Filters

Filters are widgets that enable dashboard viewers to filter on a field or to set dataset parameters. Each filter widget can be configured to filter on dataset fields or to assign values to predefined parameters in a dataset query. A single filter widget cannot use fields and parameters simultaneously.

Filter on fields

Dashboards support the following filter types for filtering fields:

• Single select dropdown

• Multi-select dropdown

• Text

• Date

• Date range

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 setting parameters:

• String

• Date

• Date and Time

• Decimal

• Integer

See Use 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. From a draft dashboard, access download options from the Data tab or right-click on a visualization on the canvas.

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.

For published dashboards, viewers can download results by right-clicking on a visualization.

Workspace admins can adjust their security settings to prevent users from downloading results with the following steps:

1. Click your username in the top bar of the Databricks workspace and select Settings.

2. Click Security.

3. Turn the SQL results download option off.

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. 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 dashboard you can share with any user in your Databricks workspace. After publishing your dashboard, the published version remains unchanged and accessible for sharing until you publish again. You can continue making modifications and improvements in a draft version without affecting the publicly shared copy.

Publishing does not automatically share dashboards with users. You can explicitly share dashboards with view permissions to users or groups.

You must have at least Can Edit permissions to publish a dashboard.

1. Open a dashboard.

2. In the Share drop-down menu in the upper-right, click Publish. The Publish dialog appears.

3. Choose the credentials to use for the published dashboard. You can optionally choose to embed your credentials.

• 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 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.

1. Click Publish.

You can share the published dashboard with any user in your Databricks workspace. For more on controlling access to your dashboard, see Dashboard ACLs.

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

Dashboard query execution

Dashboards run queries whenever users open a draft or published dashboard or perform interactions such as filtering.

Optionally, you can create a schedule on a published dashboard with embedded credentials. Creating a schedule on a published dashboard with embedded credentials allows you to send periodic PDF snapshots of the dashboard to recipients. Each scheduled update refreshes queries used by visualizations in the dashboard.

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. Interactive dashboards automatically use cached query results when underlying data has not changed since the last run of a query.

Schedule dashboards for periodic updates

You can set up scheduled updates to automatically refresh your dashboard and periodically send emails with the latest data to your subscribers.

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.

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.

Workspace admin subscription controls

Workspace admins can prevent users from distributing dashboards using subscriptions.

To prevent sharing email updates:

1. Click your username in the top bar of the Databricks workspace and select Settings.

2. Click Notifications.

3. Turn the Enable dashboard email subscriptions option off.

Changing this setting prevents all users from adding email subscribers. Dashboard editors cannot add subscribers, and dashboard viewers do not have the option to subscribe to a dashboard.

If this setting is turned off, existing subscriptions are paused, and no one can modify existing subscription lists. If this setting is turned back on, subscriptions resume using the existing list.

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.

• MobileImage: An image file optimized for viewing on mobile devices.

A maximum limit of 9MB is imposed on the combined size of the three 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 size of the PDF and DesktopImage files is greater than 9MB: Only the PDF is attached to the email. The inline message includes a link to the dashboard but no inline image for mobile or desktop viewing.

• If the combined file size of all files is greater than 9MB: The MobileImage is excluded from the email.

Transfer ownership of a dashboard

If you are a workspace admin, you can transfer ownership of a dashboard to a different user.

1. Go to the list of dashboards. Click a dashboard name to edit.

2. Click Share.

3. Click the icon at the top-right of the Sharing dialog.

4. Begin typing a username to search for and select the new owner.

5. Click Confirm.

The new owner appears in the Sharing dialog with CAN MANAGE permissions. To view dashboards listed by owner, go to the list of available dashboards by choosing the .

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.

What is share to account?

Dashboard share to account allows users to share published dashboards with users and groups outside the workspace where the dashboard was drafted.

Adding users to the Databricks account is not the same as adding them to a workspace. When users are added to an account, their credentials do not grant them automatic access to a workspace, data, or compute resources. Instead, the registration establishes their identity within the system, which Databricks will later use to verify that shared dashboards are available to only their intended recipients.

The following image shows an example of how published dashboards can be shared across multiple workspaces and at the account level.

Published dashboards can be shared with the following:

• One or more specific users assigned to the originating workspace.

• Workspace groups (including all workspace users).

• One or more specific users in the Databricks account.

• Databricks account groups (including all account users).

For more information on users and group relationships in your Databricks account, see How do admins assign users to workspaces?

Important

Dashboard account sharing requires that unified login with single sign-on (SSO) is enabled. For more information, see Unified login.

How to share a dashboard with other Databricks account users

Draft dashboards cannot be shared with users outside of the workspace. Published dashboards can be shared with Databricks account users and groups. Adding users and groups to a Databricks account does not automatically assign any workspace, data, or compute permissions. See Manage users, service principals, and groups for details on identity management with Databricks.

Use the following steps to publish and share your dashboard with account users.

• Navigate to the draft dashboard.

• Publish the dashboard with the Embed credentials (default) setting.

  Embedding your credentials means the SQL warehouse and queries use the publisher’s data and warehouse permissions to update the published dashboard. This is necessary if you want to share with users outside of the originating workspace, as they do not have their own credentials.

• Click the Share button, and use the Sharing dialog to set permissions for users and groups in your Databricks account.

  • At the top of the Sharing dialog enter workspace users, workspace groups, specific account users, or account groups.

  For users in your workspace, you can assign Can Manage, Can Edit, Can Run, or Can View permission. Account users are limited to Can View access even if assigned a higher permission in the Share modal.

  To quickly assign view access for all account users, use the Sharing settings option at the bottom of the Sharing dialog.

  

• Share the link with users.

  Click Copy link near the bottom the Sharing dialog to copy a shareable URL for the published dashboard.

Note

Users who do not have access to the workspace are limited to Can View permissions. If you grant elevated permissions such as Can Edit to a user who does not have access to the workspace, the permissions appear in the UI but are not actually applied until the user is added to the workspace.

For more information on dashboard permission levels, see Dashboard ACLs.

Network considerations

If IP access lists are configured, a dashboard published to the account is only accessible to account users if they access it from within the approved IP range, such as when using a VPN. For more information on configuring access, see Manage IP access lists.

Monitor Lakeview activity

Admins can monitor the activity on dashboards using audit logs. See Dashboards events.

Managing dashboards with the REST API

See Use Databricks APIs to manage dashboards for tutorials that demonstrate how to use 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.