Query access control

With query access control, individual permissions determine a user’s abilities. This article describes the individual permissions and how to configure query access control.

Query permissions

There are four permission levels for a query: No Permissions, Can Run, Can Edit, and Can Manage. The table lists the abilities for each permission.

Ability	No Permissions	Can View	Can Run	Can Edit	Can Manage
View own queries		x	x	x	x
See in query list		x	x	x	x
View query text		x	x	x	x
View query result		x	x	x	x
Refresh query result (or choose different parameters)			x	x	x
Include the query in a dashboard			x	x	x
Edit query text				x (1)	x
Change SQL warehouse or data source					x
Modify permissions					x
Delete query					x

(1) Requires the Run as viewer sharing setting.

Note

The principal used to execute a query is the user that created the query, not the user that clicks the Refresh button.

Sharing settings

Dashboards support two types of sharing settings: Run as viewer and Run as owner.

To configure sharing settings:

1. Click Queries in the sidebar.

2. Click a query.

3. Click the button at the top right. The Manage Permissions dialog appears.

4. In the Sharing settings > Credentials field at the bottom, select:

   • Run as viewer: the viewer’s credential is used to execute the query.

   • Run as owner: the owner’s credential is used to execute the query.

Once you accept Run as viewer, you can no longer change the credential back to Run as owner. If you revoke all sharing, you will be able to set Credentials.

Manage query permissions using the UI

1. Click Queries in the sidebar.

2. Click a query.

3. Click the button at the top right. The Manage Permissions dialog appears.

   

4. Follow the steps based on the permission type you want to grant:

   • Can Edit permission

     1. Select the Run as viewer sharing setting.

     2. Click the top field to add a user or group.

     3. Select the Can Editpermission.

     4. Click Add.

   • Can Run permission

     1. Click the top field to add a user or group.

     2. Select the Can Runpermission.

     3. Click Add.

5. Dismiss the dialog.

Manage query permissions using the API

To manage query permissions using the API, invoke methods on the /2.0/preview/sql/permissions/queries/<query-id> REST endpoint. For example, to set the Can Manage permission for the user user@example.com, use curl to run the following command:

curl -u 'token:<personal-access-token>' https://<databricks-instance>/api/2.0/preview/sql/permissions/queries/<query-id> -X POST -d '{ "access_control_list": [ { "user_name": user@example.com", "permission_level": "CAN_MANAGE" } ] }'

Replace:

• <databricks-instance> with the workspace URL of your Databricks deployment.

• <personal-access-token> with your personal access token.

• <query-id> with the query ID.

Important

Because this is a POST method, all existing permissions are overwritten. To keep any existing permissions, you must add them to the access_control_list array. In the preceding example, you would include the existing permissions you want to keep along with the new Can Manage permission for the user user@example.com.