Privileges and securable objects in Unity Catalog

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime check marked yes Unity Catalog only

A privilege is a right granted to a principal to operate on a securable object in the metastore. The privilege model and securable objects differ depending on whether you are using a Unity Catalog metastore or the legacy Hive metastore. This article describes the privilege model for the Unity Catalog. If you are using the Hive metastore, see Privileges and securable objects in the Hive metastore

Note

This article refers to the Unity Catalog privileges and inheritance model in Privilege Model version 1.0. If you created your Unity Catalog metastore during the public preview (before August 25, 2022), upgrade to Privilege Model version 1.0 by following Upgrade to privilege inheritance.

Securable objects

A securable object is an object defined in the Unity Catalog metastore on which privileges can be granted to a principal. To manage privileges on any object, you must be its owner.

Syntax

securable_object
  { CATALOG [ catalog_name ] |
    CONNECTION connection_name |
    EXTERNAL LOCATION location_name |
    FUNCTION function_name |
    METASTORE |
    SCHEMA schema_name |
    SHARE share_name |
    STORAGE CREDENTIAL credential_name |
    [ TABLE ] table_name |
    VIEW view_name |
    VOLUME volume_name
  }

You can also specify SERVER instead of CONNECTION and DATABASE instead of SCHEMA.

Parameters

Inheritance model

Securable objects in Unity Catalog are hierarchical, and privileges are inherited downward. This means that granting a privilege on the catalog automatically grants the privilege to all current and future schemas in the catalog. Similarly, privileges granted on a schema are inherited by all current and future tables and views in that schema.

For example, if you grant the SELECT privilege on a schema to a user, the user automatically is granted the SELECT privilege on all current and future tables, views, and materialized views in the schema.

Privilege types

The following table shows which Unity Catalog privileges are associated with which Unity Catalog securable objects.

Securable

Privileges

Metastore

CREATE CATALOG, CREATE CONNECTION, CREATE EXTERNAL LOCATION, CREATE PROVIDER, CREATE RECIPIENT, CREATE SHARE, CREATE STORAGE CREDENTIAL, SET SHARE PERMISSION, USE MARKETPLACE ASSETS, USE PROVIDER, USE RECIPIENT, USE SHARE

Catalog

ALL PRIVILEGES, APPLY TAG, BROWSE, CREATE SCHEMA, USE CATALOG

All users have USE CATALOG on the main catalog by default.

The following privilege types apply to securable objects in a catalog. You can grant these privileges at the catalog level to apply them to the pertinent current and future objects in the catalog.

CREATE FUNCTION, CREATE TABLE, CREATE MODEL, CREATE VOLUME, CREATE FOREIGN CATALOG, READ VOLUME, WRITE VOLUME, EXECUTE, MODIFY, SELECT, USE SCHEMA

Schema

ALL PRIVILEGES, APPLY TAG, CREATE FUNCTION, CREATE TABLE, CREATE MODEL, CREATE VOLUME, CREATE MATERIALIZED VIEW, REFRESH { MATERIALIZED VIEW | [STREAMING] TABLE }, USE SCHEMA

The following privilege types apply to securable objects within a schema. You can grant these privileges at the schema level to apply them to the pertinent current and future objects within the schema.

EXECUTE, MODIFY, SELECT, READ VOLUME, WRITE VOLUME

Table

ALL PRIVILEGES, APPLY TAG, SELECT, MODIFY

View

ALL PRIVILEGES, APPLY TAG, SELECT

Volume

ALL PRIVILEGES, READ VOLUME, WRITE VOLUME

External location

ALL PRIVILEGES, BROWSE, CREATE EXTERNAL TABLE, CREATE EXTERNAL VOLUME, READ FILES, WRITE FILES, CREATE MANAGED STORAGE

Storage credential

ALL PRIVILEGES, CREATE EXTERNAL LOCATION, CREATE EXTERNAL TABLE, READ FILES, WRITE FILES

Connection

ALL PRIVILEGES, CREATE FOREIGN CATALOG, USE CONNECTION

Function

ALL PRIVILEGES, EXECUTE

Registered Model

ALL PRIVILEGES, APPLY TAG, EXECUTE

Share

SELECT (Can be granted to RECIPIENT)

Recipient

None

Provider

None

  • APPLY TAG

    Apply and edit tags on an object.

  • ALL PRIVILEGES

    Used to grant or revoke all privileges applicable to the securable object and its child objects without explicitly specifying them. This expands to all available privileges at the time permissions checks are made. It does not individually grant the user each applicable privilege at the time of the grant.

    When ALL PRIVILEGES is revoked only the ALL PRIVILEGES privilege itself is revoked. Users retain any other privileges that were granted to them separately.

  • BROWSE

    Preview

    This feature is in Public Preview.

    View an object’s metadata using Catalog Explorer, the schema browser, search results, the lineage graph, information_schema, and the REST API. The user does not require the USE CATALOG privilege on the parent catalog or USE SCHEMA on the parent schema.

  • CREATE CATALOG

    Create catalogs in a Unity Catalog metastore.

  • CREATE CONNECTION

    Create foreign connections in a Unity Catalog metastore.

  • CREATE EXTERNAL LOCATION

    Create an external location using the storage credential. When applied to a storage credential, allows a user to create an external location using the storage credential. This privilege also needs to be granted to a user on the metastore to allow them to create an external location in that metastore.

  • CREATE EXTERNAL TABLE

    Create external tables using the storage credential or external location.

  • CREATE EXTERNAL VOLUME

    Create external volumes using the external location.

  • CREATE FOREIGN CATALOG

    Create catalogs on a foreign connection. Each foreign catalog then exposes the schemas available in the federated target system.

  • CREATE FUNCTION

    Create a function in a schema. The user also requires the USE CATALOG privilege on the catalog and the USE SCHEMA privilege on the schema.

  • CREATE MANAGED STORAGE

    Allows a user to specify a location for storing managed tables at the catalog or schema level, overriding the default root storage for the Unity Catalog metastore.

  • CREATE MODEL

    Allows a user to create an MLflow registered model in the schema. Since privileges are inherited, CREATE MODEL can also be granted on a catalog, which allows a user to create a registered model in any existing or future schema in the catalog.

    The user must also have the USE CATALOG privilege on the parent catalog and USE SCHEMA on the parent schema.

  • CREATE PROVIDER

    (For Delta Sharing data recipients) Create a provider in a Unity Catalog metastore.

  • CREATE RECIPIENT

    (For Delta Sharing data providers) Create a recipient in a Unity Catalog metastore.

  • CREATE SCHEMA

    Create a schema in a catalog. The user also requires the USE CATALOG privilege on the catalog.

  • CREATE SHARE

    (For Delta Sharing data providers) Create a share in a Unity Catalog metastore.

  • CREATE STORAGE CREDENTIAL

    Create a storage credential in a Unity Catalog metastore.

  • CREATE TABLE

    Create a table or view in a schema. The user also requires the USE CATALOG privilege on the catalog and the USE SCHEMA privilege on the schema. To create an external table, the user also requires the CREATE EXTERNAL TABLE privilege on the external location or storage credential.

  • CREATE VOLUME

    Create a volume in a schema. The user also requires the USE CATALOG privilege on the catalog and the USE SCHEMA privilege on the schema. To create an external volume, the user also requires the CREATE EXTERNAL VOLUME privilege on the external location.

  • EXECUTE

    Invoke a user defined function. The user also requires the USE CATALOG privilege on the catalog and the USE SCHEMA privilege on the schema.

  • MODIFY

    COPY INTO, UPDATE DELETE, INSERT, or MERGE INTO the table.

  • READ FILES

    Query files directly using the storage credential or external location.

  • READ VOLUME

    Query files within the volume.

  • SELECT

    Query a table or view, invoke a user defined or anonymous function, or select ANY FILE. The user needs SELECT on the table, view, or function, as well as USE CATALOG on the object’s catalog and USE SCHEMA on the object’s schema.

  • SET SHARE PERMISSION

    In Delta Sharing, this permission, combined with USE SHARE and USE RECIPIENT (or recipient ownership), gives a provider user the ability to grant a recipient access to a share. Combined with USE SHARE, it gives the ability to transfer ownership of a share to another user, group, or service principal.

  • USE CATALOG

    Required, but not sufficient to reference any objects in a catalog. The principal also needs to have privileges on the individual securable objects. Not required for a user to use read an object’s metadata using the BROWSE privilege.

  • USE CONNECTION

    Required to read metadata on a foreign connection or all foreign connections when used on the metastore.

  • USE MARKETPLACE ASSETS

    Enabled by default for all Unity Catalog metastores. In Databricks Marketplace, this privilege gives a user the ability to get instant access or request access for data products shared in a Marketplace listing. It also allows a user to access the read-only catalog that is created when a provider shares a data product. Without this privilege, the user would require the CREATE CATALOG and USE PROVIDER privileges or the metastore admin role. This enables you to limit the number of users with those powerful permissions.

  • USE PROVIDER

    In Delta Sharing, gives a recipient user read-only access to all providers in a recipient metastore and their shares. Combined with the CREATE CATALOG privilege, this privilege allows a recipient user who is not a metastore admin to mount a share as a catalog. This enables you to limit the number of users with the powerful metastore admin role.

  • USE RECIPIENT

    In Delta Sharing, gives a provider user read-only access to all recipients in a provider metastore and their shares. This allows a provider user who is not a metastore admin to view recipient details, recipient authentication status, and the list of shares that the provider has shared with the recipient.

    In Databricks Marketplace, this gives provider users the ability to view listings and consumer requests in the Provider console.

  • USE SCHEMA

    Required, but not sufficient to reference any objects in a schema. The principal also needs to have privileges on the individual securable objects. Not required for a user to use read an object’s metadata using the BROWSE privilege.

  • USE SHARE

    In Delta Sharing, gives a provider user read-only access to all shares defined in a provider metastore. This allows a provider user who is not a metastore admin to list shares and list the assets (tables and notebooks) in a share, along with the share’s recipients.

    In Databricks Marketplace, this gives provider users the ability to view details about the data shared in a listing.

  • WRITE FILES

    Directly COPY INTO files governed by the storage credential or external location.

  • WRITE VOLUME

    Directly COPY INTO files into a volume.

Examples

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

-- Revoke a privilege from the general public group.
> REVOKE USE SCHEMA ON SCHEMA some_schema FROM `alf@melmak.et`;