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:
Click <Queries in the sidebar.
Click a query.
Click the
button at the top right. The Manage Permissions dialog appears.
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
Click Queries in the sidebar.
Click a query.
Click the
button at the top right. The Manage Permissions dialog appears.
Follow the steps based on the permission type you want to grant:
Can Edit permission
Select the Run as viewer sharing setting.
Click the top field to add a user or group.
Select the Can Edit permission.
Click Add.
Can Run permission
Click the top field to add a user or group.
Select the Can Run permission.
Click Add.
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
.