Query access control

With query access control, individual permissions determine a user’s ability to perform and view queries in Databricks SQL. This article describes the individual permissions and how to configure query access control.

Query permissions

There are five permission levels for a query: No Permissions, Can View, 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

Queries 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. The viewer must also have at least Can Use permissions on the warehouse.

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

Manage query permission with folders

You can manage query permissions by adding queries to folders. Queries in a folder inherit all permissions settings of that folder. For example, a user that has Can Run permission on a folder has Can Run permission on the queries in that folder. To learn about configuring permissions on folders, see Folder permissions.

To learn more about organizing queries into folders, see Workspace browser.

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 Edit permission.

     4. Click Add.

   • Can Run permission

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

     2. Select the Can Run permission.

     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.