Dashboards

You can use dashboards to build data visualizations and share reports 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. When published, your dashboards can be shared with anyone registered to your Databricks account, even if they don’t have access to the workspace. See Share a dashboard.

important

• Databricks recommends using AI/BI dashboards (formerly Lakeview dashboards). Earlier versions of dashboards, previously referred to as Databricks SQL dashboards are now called legacy dashboards. As of April 7, 2025, you can no longer create or clone new legacy dashboards.
• Convert legacy dashboards using the migration tool or the REST API.
  • See Clone a legacy dashboard to an AI/BI dashboard for instructions on using the built-in migration tool.
  • See Migrate a dashboard for instructions on migrating legacy dashboards using the API.
  • See the Migrate dashboard POST /api/2.0/lakeview/dashboards/migrate endpoint in the REST API reference.

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 can be organized into multi-page reports. Dashboard editors can build and configure their dashboards by adding widgets such as visualizations, filters, text, and images.

note

You can define up to 100 datasets per dashboard. The Canvas can contain up to 10 pages. Dashboards can hold up to 100 widgets across all pages.

View and organize dashboards

You can access dashboards from the workspace browser along with other 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 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.

Draft and collaborate on a dashboard

New dashboards open as drafts. Changes to a draft dashboard are saved automatically, but they do not automatically sync with the published version if it exists. For details about publishing dashboards, see Publish a dashboard.

To discard edits and restore the draft to the most recently published version, click the kebab menu in the upper-right corner of the dashboard, and click Discard changes.

You can collaborate on a draft by sharing it with users in your workspace. Users with access interact with the dashboard using their own credentials. You cannot share draft dashboards with users outside the workspace. For more information about permission levels, see AI/BI dashboard ACLs.

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.

note

Every dataset is defined by a query. When selecting an existing Unity Catalog table or view, the query defaults to SELECT * on that object, which you can modify to refine the dataset.

You can create multiple datasets by adding queries or selecting additional tables or views. To adjust the display order of datasets, drag and drop their names into the desired position.

To format a query in the dataset editor, right-click within the editor and select Format document. To customize how your SQL queries are formatted, see Custom format SQL statements.

For more details on creating and managing dashboard datasets, see Create and manage dashboard datasets.

Add pages, visualizations, text, and filters to the canvas

Use the Canvas tab to construct your dashboard. A canvas can contain up to ten pages. You can add visualizations, text, and filter widgets to each page. Use multiple pages to organize your content presentation, minimize scrolling, and improve dashboard readability. Use the toolbar at the bottom of each page to add widgets such as visualizations, text boxes, and filters.

Create multi-page reports

New dashboards start with a single page named Untitled page. To edit the name of a page, double-click the title and enter the new name into the text field. Naming conflicts resolve automatically by appending a number to the title.

To view the content on a page, click the title to select it.

Add and remove pages

To add a new page:

• Click to the right of the current page title on the canvas. By default, your new page is named Untitled page.
• (Optional) Double-click the page title and enter a new name to rename the page.

To remove a page:

• Click the kebab menu to the right of the page title.
• Click Delete to delete the page.

note

Deleting a page also deletes all of the widgets on that page. If you delete all pages, click Create a page to start building your dashboard again.

Clone a page

To clone a page:

1. Click the page title to select it.
2. Click the in the title tile, then click Clone.

The new page is an exact copy of the original, including all widgets. The underlying datasets remain unchanged.

Visualizations

Create a visualization by adding a visualization widget to a page on the canvas. Supported visualizations include area, bar, box, combo, counter, heatmap, histogram, line, pie, pivot, sankey, scatter, and table chart types. For a complete list of available visualization types and example configuration values, see Dashboard visualizations 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 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.

For details about how to apply custom formatting to your charts, see Dashboard visualizations. 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.

Generate a forecast

If AI Forecast (Public Preview) is enabled in your workspace, you can apply predictive forecasting to line charts to visualize future trends and patterns. Your line chart must have a temporal date field on the x-axis and a single numeric field on the y-axis.

To create a chart with AI forecast:

• With your line chart selected, click + in the Forecast section of the visualization editor.
• Click Clone with AI Forecast in the dialog that appears. A new line chart is created with forecasting applied.

To learn more about the function that generates the forecast, see ai_forecast function.

Troubleshooting visualizations

Editing a dataset can cause a previously configured visualization to display an error message. This can happen when dataset fields are removed or renamed. If your visualization shows an error, try the following actions:

• Refresh the dashboard.
• Click Show error on the visualization widget to view a detailed error message that might help identify issues in the dataset.
• Review the SQL used to generate the dataset associated with the visualization.
• Remove any broken filters that reference the dataset.
• Remove any other visualizations that use the dataset.

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. For details about basic markdown syntax, see the Markdown guide.

Add images to text widgets

To add an image, use the following Markdown syntax:

![Description](path-or-URL-to-image)

This syntax includes an exclamation mark (!), followed by descriptive text in brackets ([ ]), and the image path or URL in parentheses (( )). You can display images in a text widget using a Volume path, a base64-encoded string, or a publicly hosted URL. To resize the image, adjust the widget’s dimensions.

Use one of the following methods to specify the image source.

Use a Volume path

Use the following format, replacing the placeholders with your Databricks instance name and the path to the image in your Volume:

https://<databricks-instance>/ajax-api/2.0/fs/files/<Volumes/path/to/image>

Your instance name is in the first part of the URL that appears when you log in to your Databricks deployment. Some deployments include a workspace ID. Do not include the workspace ID when constructing the path. To learn more, see Workspace instance names, URLs, and IDs.

To find the Volume path:

1. Click Catalog in the sidebar to open Catalog Explorer.
2. Click the image file in the schema browser.
3. Click the kebab menu next to the file name, then click Copy Path.

See What are Unity Catalog volumes? to learn more about storing data in Volumes.

Use a local file

To use a local file, first encode it as a base64 string. Then use the following Markdown syntax:

![description](data:image/webp;base64,<base64-encoded-string>)

note

If you’re comfortable with command-line utilities, use the base64 tool to convert your file. Alternatively, there are many free online resources that you can use to base64 encode files.

Use a publicly hosted image

For publicly hosted images, insert the public URL that points to the image.

![description](URL)

Replace the sample text with the description and URL of the image you want to show. 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).

note

When you publish your dashboard with embedded credentials, viewers use your credentials to access the included images. If your dashboard is not published with embedded credentials, you must explicitly grant access to users for image files stored on Databricks. Use Catalog Explorer to check, grant, and revoke permissions on the image files that you want to include. Click Catalog in the sidebar to open the Catalog Explorer UI.

Apply cross-filtering

When you're exploring a dashboard, you might notice specific trends or values that you want to investigate further. Although filters might already be applied, they might not capture every viewer’s interest. Cross-filtering allows viewers to filter dashboard data by interacting directly with visualizations. This is useful for exploring patterns, outliers, or specific segments without manually editing filter controls.

You can use cross-filtering to:

• Focus on specific data segments by selecting values in one or more charts.
• Drill into hierarchical data by clicking aggregated values. For example, click a year in a bar chart to filter other visualizations by that year. Then click a month or week to continue narrowing the scope.

Cross-filtering is automatically applied to supported visualizations that use the same dataset.

The following chart types support cross-filtering:

• Bar
• Box plot
• Heatmap
• Histogram
• Pie
• Scatter
• Point map

When you apply a filter by selecting a chart element, all other visualizations based on the same dataset automatically update to reflect the filtered data.

Filter related visualizations

To explore data using cross-filtering:

1. Click a data point in a visualization, such as a bar in a bar chart or a cell in a heatmap.
2. The dashboard applies a filter based on the selected value.

All other visualizations that share the same dataset update accordingly.

Use filters

Filters are dashboard widgets that help viewers narrow down results and refine data in visualizations, similar to slicers in other BI tools. You can configure them to filter values based on one or more dataset columns (also referred to as fields) or parameters defined in the SQL queries that create datasets. To learn how to configure filters for visualizations on a dashboard, see Use dashboard filters.

Copy widgets

Use keyboard shortcuts to copy a selected widget and paste it back on the canvas. Use Command-C (Mac) or Ctrl-C (Windows/Linux) to copy, and Command-V (Mac) or Ctrl-V (Windows/Linux) to paste. 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:

1. Right-click on a widget.
2. 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.

To learn how to download a published dashboard as a PDF, see Download a published dashboard.

Publish a dashboard

Publishing a dashboard creates a clean copy of the current draft. The publisher's compute credentials are embedded in the published dashboard and used to process all subsequent updates, regardless of which user or service initiates the update. You must have at least CAN EDIT permissions to publish a dashboard.

After publishing, the published version remains unchanged 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. Registered users with access can view the published version, and it continues to be emailed to subscribers if any exist. For more on managing dashboard access, see Share a dashboard.

Published dashboards are not versioned and should not be used for version control. You can revert a draft dashboard back to the last published version. See Draft and collaborate on a dashboard.

When publishing, choose one of the following options:

• Embed credentials (default): Viewers run queries using the publisher’s data permissions. This allows users to view the dashboard even if they do not have direct access to the underlying data. This might expose data to users who have not been granted direct access to it. This is the default option.
• Don’t embed credentials: Viewers run queries using their own credentials. Their data permissions determine what they can see, and they must have access to the underlying data to view results. For users with access to the dashboard’s workspace, the dashboard publisher’s compute credentials are used to process the update. Users without workspace access do not have the necessary permissions to access the compute that runs dashboard queries or view the presented data.

note

All dashboard viewers must authenticate to access the dashboard, regardless of the credential setting. To change the credential setting, republish the dashboard with your updated selection.

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.

Use a service principal to publish and share dashboards

Use the REST API to publish and share dashboards with embedded credentials associated with a service principal. When you run an API call using the service principal's token, users access data based on the service principal's permissions. This allows users without direct data or compute permissions to view the dashboard and run queries. Users must be registered with your Databricks account. For details about using the REST API to manage your dashboards, see Lakeview in the REST API reference.

Download a published dashboard

After a published dashboard loads, use the following steps to download it as a PDF:

• Click the near the upper-right corner of the dashboard.
• Click Download as PDF.

Enable a Genie space from your dashboard

Preview

This feature is in Public Preview.

When you create a dashboard, a Genie space is automatically created for you. A Genie space is a no-code interface that allows business users to conduct self-serve data analytics using natural language. The automatically created Genie space starts as a draft that you can use to preview the space. The draft Genie space stays in sync with your draft dashboard as you add and remove datasets and visualizations.

When you publish your dashboard, you can choose to publish the associated draft Genie space or link to an existing Genie space instead.

Publishing a Genie space associated with your dashboard allows viewers to explore dashboard data in a different way. Instead of gaining insights based only on what’s available on a dashboard, they engage with the data by asking their own questions for deeper analysis. See What is an AI/BI Genie space.

Publishing the Genie space adds an Ask Genie button to the published dashboard. When dashboard viewers click on that button, a chat interface opens on the dashboard and prompts users to ask questions about the data.

To publish the associated Genie space, use the following steps:

1. Click Publish.
2. The Enable Genie toggle is on by default. Click the toggle to turn it on.
3. (Optional) To link an existing Genie space, select the Link existing Genie space radio button and paste in the associated URL. If this option is not selected, a new Genie space is based on your dashboard is automatically generated for you.
4. Click Publish in the Publish dialog.

note

The draft and published Genie spaces are independent, much like the draft and published versions of your dashboard. Any changes made to the draft dashboard are reflected in the published Genie space only when the dashboard is republished. Draft and published Genie spaces are companions to your dashboard. They do not appear in your file browser or the Genie listing page.

To open the published Genie space in a new window:

1. Click the kebab menu in the upper-right corner of the chat window
2. Click Open Genie Space.

To preview your draft Genie space:

1. Click the kebab menu in the upper-right corner of your dashboard.
2. Click Open the draft Genie space.

note

You cannot edit the instructions for this Genie space from the Genie space UI. Your draft Genie space only changes when you make changes to the draft dashboard.

Ask Genie about a specific chart

To ask Genie about a specific dashboard chart:

1. Click Ask Genie from a Genie-enabled published dashboard.
2. Click a dashboard chart to select it. Genie displays the selected chart title in the chat window.
3. Ask questions about the data represented in the selected chart.

Permissions for linked Genie spaces

Permissions on the associated Genie space mirror those in place on the dashboard, but access is limited to users with workspace access. Even if your dashboard is shared with embedded credentials, only users with workspace access can interact with the Genie space.

Viewers use their own credentials to access the compute and data necessary to power the Genie space. They must have at least SELECT permission on the tables used in the Genie space.

Share a dashboard

You can securely share dashboards with anyone in your account. For users who are assigned to your workspace, you can grant access and set varying permission levels as you would with other workspace objects. For users who are not assigned to your workspace, you can share dashboards at the account level, allowing registered users to view and run your dashboard.

For details on how admins can set up your account for sharing at the account level, see Dashboard administration guide. For details on sharing your dashboard at the account and workspace levels, see Share a dashboard.

important

Dashboard account-level sharing supports email and one-time passcode authentication, and unified login with single sign-on (SSO). If a dashboard is shared when the recipient uses a one-time passcode login and then the account is later configured for SSO with unified login, account admins should verify dashboard recipients are allowed to access that Databricks account using their identity provider configuration. The users who aren’t allowed to log in using SSO will no longer be able to access dashboards that were previously shared with them.

Embed dashboards in websites and applications

You can embed your published dashboard into external websites and applications using an iframe. See Embed a dashboard.

If you are a workspace admin who wants to manage the external sites where dashboards can be embedded, see Manage dashboard embedding.

Schedules and subscriptions

You can set up scheduled updates to automatically refresh your dashboard’s cache 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 that published dashboards with embedded credentials run periodically. Each dashboard can have up to ten schedules.

See Manage scheduled dashboard updates and subscriptions.

Schedule updates using Databricks Jobs

You can configure a task to routinely update an existing published dashboard. To learn more about orchestrating workflows with Databricks Jobs, see Orchestration using Databricks Jobs. To learn how to configure a dashboard task, see Dashboard task for jobs.

note

Schedule and subscriber lists that you create using the dashboard UI or API are distinct from scheduling and automation associated with a job. See Automating jobs with schedules and triggers.

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

Edit a dashboard file

The serialized lvdash.json file that you have after exporting a dashboard includes complete query syntax and widget settings. In some cases, such as editing an automatically generated page or widget name value, it's useful to be able to edit this file directly.

To edit automatically generated values page and widget ID values:

1. Export the draft dashboard and open the .lvdash.json file in a text editor.
2. Edit the name values associated with the page and widget. Save the file.
3. Import the file to your workspace and republish.

note

The name value in the JSON file is separate from the displayName field, which defines the page name shown in the UI.

Best practice for managing dashboard versions

Source control for dashboards is now in Public Preview. Workspace admins can control workspace access to the Public Preview from the Previews page. By default, the Support Dashboards in Git folder preview is On. See Source control dashboards.

If you cannot enable the Public Preview, the recommended workflow is as follows:

1. Export your dashboard as a JSON file. The file format is lvdash.json.
2. Add that file to a version control system, such as Git.
3. Edit the file. You can edit values in the text file directly or upload it back to your workspace and make changes in the UI.
4. Save the new file. If you’ve made changes in the UI, export your new file. Use your version control system to track dashboard changes and versions.
5. Update the existing dashboard. From the existing draft dashboard:
   1. Click the kebab menu in the upper-right corner and then click Replace dashboard.
   2. Click Choose file in the Replace dashboard from file dialog. Then, click Overwrite.

Manage dashboards programmatically

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, and how to create, manage, and share them.

To learn how to manage an AI/BI dashboard using Databricks Asset Bundles, see dashboard. For an example bundle that defines a dashboard, see the bundle-examples GitHub repository.

Databricks also offers a Terraform provider. See the Databricks Terraform documentation.