dashboards

Creates, updates, deletes, gets or lists a dashboards resource.

Overview

Name	dashboards
Type	Resource
Id	databricks_workspace.sql.dashboards

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	The ID for this dashboard.
name	string	The title of the dashboard that appears in list views and at the top of the dashboard page.
user_id	integer	The ID of the user who owns the dashboard.
can_edit	boolean	Whether the authenticated user can edit the query definition.
created_at	string	Timestamp when this dashboard was created.
dashboard_filters_enabled	boolean	In the web application, query filters that share a name are coupled to a single selection box if this value is `true`.
is_archived	boolean	Indicates whether a dashboard is trashed. Trashed dashboards won't appear in list views. If this boolean is `true`, the `options` property for this dashboard includes a `moved_to_trash_at` timestamp. Items in trash are permanently deleted after 30 days.
is_draft	boolean	Whether a dashboard is a draft. Draft dashboards only appear in list views for their owners.
is_favorite	boolean	Indicates whether this query object appears in the current user's favorites list. This flag determines whether the star icon for favorites is selected.
▶options	object
parent	string	The identifier of the workspace folder containing the object.
permission_tier	string	* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query * `CAN_MANAGE`: Can manage the query (CAN_EDIT, CAN_MANAGE, CAN_RUN, CAN_VIEW)
slug	string	URL slug. Usually mirrors the query name with dashes (`-`) instead of spaces. Appears in the URL for this query.
tags	array
updated_at	string	Timestamp when this dashboard was last updated.
▶user	object
▶widgets	array

list

Name	Datatype	Description
id	string	The ID for this dashboard.
name	string	The title of the dashboard that appears in list views and at the top of the dashboard page.
user_id	integer	The ID of the user who owns the dashboard.
can_edit	boolean	Whether the authenticated user can edit the query definition.
created_at	string	Timestamp when this dashboard was created.
dashboard_filters_enabled	boolean	In the web application, query filters that share a name are coupled to a single selection box if this value is `true`.
is_archived	boolean	Indicates whether a dashboard is trashed. Trashed dashboards won't appear in list views. If this boolean is `true`, the `options` property for this dashboard includes a `moved_to_trash_at` timestamp. Items in trash are permanently deleted after 30 days.
is_draft	boolean	Whether a dashboard is a draft. Draft dashboards only appear in list views for their owners.
is_favorite	boolean	Indicates whether this query object appears in the current user's favorites list. This flag determines whether the star icon for favorites is selected.
▶options	object
parent	string	The identifier of the workspace folder containing the object.
permission_tier	string	* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query * `CAN_MANAGE`: Can manage the query (CAN_EDIT, CAN_MANAGE, CAN_RUN, CAN_VIEW)
slug	string	URL slug. Usually mirrors the query name with dashes (`-`) instead of spaces. Appears in the URL for this query.
tags	array
updated_at	string	Timestamp when this dashboard was last updated.
▶user	object
▶widgets	array

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	dashboard_id, deployment_name		Returns a JSON representation of a dashboard object, including its visualization and query objects.
list	select	deployment_name	order, page, page_size, q	Fetch a paginated list of dashboard objects.
update	insert	dashboard_id, deployment_name		Modify this dashboard definition. This operation only affects attributes of the dashboard object. It
delete	delete	dashboard_id, deployment_name		Moves a dashboard to the trash. Trashed dashboards do not appear in list views or searches, and cannot
restore	exec	dashboard_id, deployment_name		A restored dashboard appears in list views and searches and can be shared.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
dashboard_id	string	str
deployment_name	string	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
order	string	Name of dashboard attribute to order by.
page	integer	Page number to retrieve.
page_size	integer	Number of dashboards to return per page.
q	string	Full text search term.

SELECT examples

get

Returns a JSON representation of a dashboard object, including its visualization and query objects.

SELECT
id,
name,
user_id,
can_edit,
created_at,
dashboard_filters_enabled,
is_archived,
is_draft,
is_favorite,
options,
parent,
permission_tier,
slug,
tags,
updated_at,
user,
widgets
FROM databricks_workspace.sql.dashboards
WHERE dashboard_id = '{{ dashboard_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

list

Fetch a paginated list of dashboard objects.

SELECT
id,
name,
user_id,
can_edit,
created_at,
dashboard_filters_enabled,
is_archived,
is_draft,
is_favorite,
options,
parent,
permission_tier,
slug,
tags,
updated_at,
user,
widgets
FROM databricks_workspace.sql.dashboards
WHERE deployment_name = '{{ deployment_name }}' -- required
AND order = '{{ order }}'
AND page = '{{ page }}'
AND page_size = '{{ page_size }}'
AND q = '{{ q }}'
;

INSERT examples

update

Modify this dashboard definition. This operation only affects attributes of the dashboard object. It

INSERT INTO databricks_workspace.sql.dashboards (
name,
run_as_role,
tags,
dashboard_id,
deployment_name
)
SELECT 
'{{ name }}',
'{{ run_as_role }}',
'{{ tags }}',
'{{ dashboard_id }}',
'{{ deployment_name }}'
RETURNING
id,
name,
user_id,
can_edit,
created_at,
dashboard_filters_enabled,
is_archived,
is_draft,
is_favorite,
options,
parent,
permission_tier,
slug,
tags,
updated_at,
user,
widgets
;

Manifest

# Description fields are for documentation purposes
- name: dashboards
props:
  - name: dashboard_id
    value: "{{ dashboard_id }}"
    description: Required parameter for the dashboards resource.
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the dashboards resource.
  - name: name
    value: "{{ name }}"
  - name: run_as_role
    value: "{{ run_as_role }}"
    description: |
      Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior)
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      :returns: :class:`Dashboard`

DELETE examples

delete

Moves a dashboard to the trash. Trashed dashboards do not appear in list views or searches, and cannot

DELETE FROM databricks_workspace.sql.dashboards
WHERE dashboard_id = '{{ dashboard_id }}' --required
AND deployment_name = '{{ deployment_name }}' --required
;

Lifecycle Methods

restore

A restored dashboard appears in list views and searches and can be shared.

EXEC databricks_workspace.sql.dashboards.restore 
@dashboard_id='{{ dashboard_id }}' --required, 
@deployment_name='{{ deployment_name }}' --required
;