Use dashboard APIs to create and manage dashboards

Article
10/15/2024

The Databricks REST API includes management tools specifically for managing AI/BI dashboards. This article demonstrates how to create a new AI/BI dashboard from an existing legacy dashboard. Then, it shows how to use API tools to manage the dashboard.

Note

AI/BI dashboards were previously known as Lakeview dashboards. The Lakeview API still retains that name.

Prerequisites

You need a personal access token to connect with your workspace. See Azure Databricks personal access token authentication.
You need the workspace URL(s) that you want to access. See Workspace instance names, URLs, and IDs
Familiarity with the Databricks REST API reference.

Migrate a dashboard

You can create a new AI/BI dashboard from an existing legacy dashboard. The Migrate dashboard endpoint in the Lakeview API requires the source_dashboard_id. Optionally, you can include a display name and a path where you want the new dashboard to be stored.

Get Databricks SQL dashboards

To get the source_dashboard_id, use the Databricks SQL dashboards API to get a list of all of the dashboards in your workspace. Each dashboard object in the results list includes a UUID that you can use to refer to the legacy dashboard across Azure Databricks REST API services.

The following example shows a sample request and response for the Get dashboard objects endpoint. Some response details have been omitted for clarity. See GET /api/2.0/preview/sql/dashboards for a full description of this endpoint and sample response.

The UUID for a legacy dashboard is the id from the top level of the list of objects returned in results. For legacy dashboards, the UUID looks like 4e443c27-9f61-4f2e-a12d-ea5668460bf1.

GET /api/2.0/preview/sql/dashboards

Query Parameters:

{
"page_size": <optional>,
"page": <optional>,
"order": <optional>
"q": <optional>
}

Response:

{
  "count": 1,
  "page": 1,
  "page_size": 25,
  "results": [
    {
      "id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
      "slug": "sales-dashboard",
      "parent": "folders/2025532471912059",
      ...
    }
  ]
}

Migrate legacy dashboard

Use the UUID associated with the legacy dashboard to create a copy that is automatically converted to a new AI/BI dashboard. This works like the Clone to AI/BI dashboard tool available in the UI. See Clone a legacy dashboard to an AI/BI dashboard to learn how to perform this operation using the Azure Databricks UI.

The UUID of the legacy dashboard you want to convert is required in the request body. Optionally, you can include a new display_name value and a parent_path that identifies the workspace path of the folder where you want the converted dashboard to be stored.

The response includes a dashboard_id, the UUID for the new dashboard. The UUID for a AI/BI dashboard is a 32-digit alphanumeric value like 04aab30f99ea444490c10c85852f216c. You can use it to identify this dashboard in the Lakeview namespace and across different Azure Databricks REST API services.

The following example shows a sample request and response. See POST /api/2.0/lakeview/dashboards/migrate.

POST /api/2.0/lakeview/dashboards/migrate

Request body parameters:
{
  "source_dashboard_id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
  "display_name": "Monthly Traffic Report",
  "parent_path": "/path/to/dir"
}

Response:
{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Get a draft dashboard

You can use the dashboard_id to pull dashboard details from a draft dashboard. The following sample request and response includes details for the current version of the draft dashboard in the workspace.

The etag field tracks the latest version of the dashboard. You can use this to verify the version before making additional updates.

GET /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Update a dashboard

You can use the dashboard_id in the previous response to update the new AI/BI dashboard created with that operation. The following example shows a sample request and response. The dashboard_id from the previous example is included as a path parameter.

The display_name and warehouse_id have been changed. The updated dashboard has a new name and assigned default warehouse, as shown in the response. The etag field is optional. If the version specified in the etag does not match the current version, the update is rejected.

PATCH /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611980"
}

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611981",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Create a dashboard

You can use the Create dashboard endpoint in the Lakeview API to move your dashboard between workspaces. The following example includes a sample request body and response that creates a new dashboard. The serialized_dashboard key from the previous example contains all the necessary details to create a duplicate draft dashboard.

The sample includes a new warehouse_id value corresponding to a warehouse in the new workspace. See POST /api/2.0/lakeview/dashboards.

POST /api/2.0/lakeview/dashboards

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "parent_path": "/path/to/dir"
}

Response:

{
  "dashboard_id": "1e23fd84b6ac7894e2b053907dca9b2f",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "5e2f98ab3476cfd0",
  "etag": "14350695",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

The only required property in the request body is a display_name. This tool can copy dashboard content or create new, blank dashboards.

Publish a dashboard

You can use the Publish dashboard endpoint to publish a dashboard, set credentials for viewers, and override the warehouse_id set in the draft dashboard. You must include the dashboard’s UUID as a path parameter.

The request body sets the embed_credentials property to false. By default, embed_credentials is set to true. Embedding credentials allows account-level users to view dashboard data. See Publish a dashboard. A new warehouse_id value is omitted, so the published dashboard uses the same warehouse assigned to the draft dashboard.

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Request body:

{
  "embed_credentials": false
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Get published dashboard

The response from GET /api/2.0/lakeview/dashboards/{dashboard_id}/published is similar to the response provided in the previous example. The dashboard_id is included as a path parameter.

GET /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Unpublish a dashboard

The draft dashboard is retained when you use the Lakeview API to unpublish a dashboard. This request deletes the published version of the dashboard.

The following example uses the dashboard_id from the previous example. A successful request yields a 200 status code. There is no response body.

DELETE /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Trash dashboard

Use DELETE /api/2.0/lakeview/dashboards/{dashboard_id} to send a draft dashboard to the trash. The dashboard can still be recovered.