Principal

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime

A principal is a user, service principal, or group known to the metastore. Principals can be granted privileges and can own securable objects.

Syntax 

{ `<user>@<domain-name>` |
  `<sp-application-id>` |
  group_name |
  users |
  `account users` }

Any object name that includes special characters, such as hyphens or dashes (-), must be surrounded by backticks ( ` ` ). Object names with underscores (_) don’t require backticks. See Names.

Parameters

  • <user>@<domain-name>

    An individual user. You must escape the identifier with back-ticks (`) because of the @ character in the username.

  • <sp-application-id>

    A service principal, specified by its applicationId value. You must escape the identifier with back-ticks (`) because of the dash (-) characters in the ID.

  • group_name

    An identifier that specifies a group of users or groups. You must escape the identifier with back-ticks (`) if the group name uses special characters, like dashes (-).

  • users

    The root group to which all users in the workspace belong. You cannot grant users privileges on securable objects in Unity Catalog because it is a workspace-local group.

  • account users

    The root group to which all users in the account belong. You must escape the identifier with back-ticks (`) because of the blank space character.

Workspace-local and account groups

Databricks has the concept of account groups and workspace-local groups, with special behaviors:

  • Account groups Account groups can be created by account admins and workspace admins of identity-federated workspaces. They can be granted access to identity-federated workspaces and privileges to securable objects in the Unity Catalog.

  • Workspace-local groups can be created only by workspace admins. These groups are identified as workspace-local in the workspace admin settings page and on the workspace Permissions tab in the account console. Workspace-local groups cannot be assigned to additional workspaces or granted privileges to securable objects in the Unity Catalog. The system groups users and admins are a workspace-local groups.

Examples 

-- Granting a privilege to the user alf@melmak.et
> GRANT SELECT ON TABLE t TO `alf@melmak.et`;

-- Granting a privilege to the service principal fab9e00e-ca35-11ec-9d64-0242ac120002
> GRANT SELECT ON TABLE t TO `fab9e00e-ca35-11ec-9d64-0242ac120002`;

-- Revoking a privilege from the general public group.
> REVOKE SELECT ON TABLE t FROM `account users`;

-- Transferring ownership of an object to `some-group`
> ALTER SCHEMA some_schema OWNER TO `some-group`;