Unity Catalog privileges and securable objects

This article describes the Unity Catalog privilege model. To learn about how this model differs from the Hive metastore, see Work with Unity Catalog and the legacy 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), you can upgrade to Privilege Model version 1.0 following Upgrade to privilege inheritance

Manage privileges

Privileges can be granted by either a metastore admin, the owner of an object, or the owner of the catalog or schema that contains the object. You can manage privileges for metastore objects by using SQL commands, Unity Catalog CLI, or in Data Explorer. To learn how to use Data Explorer to manage privileges see, Manage Unity Catalog permissions in Data Explorer.

To manage privileges in SQL, you use GRANT and REVOKE statements in a notebook or the Databricks SQL query editor, using the syntax:

GRANT privilege_type ON securable_object TO principal

Where:

For example, the following command grants a group named finance access to create tables in schema named default with the parent catalog named main:

GRANT CREATE TABLE ON SCHEMA main.default TO finance;

For more information about granting privileges using SQL commands, see Privileges and securable objects in Unity Catalog.

You can also manage privileges by using the Databricks Terraform provider and databricks_grants.

Securable objects in Unity Catalog

A securable object is an object defined in the Unity Catalog metastore on which privileges can be granted to a principal. Securable objects in Unity Catalog are hierarchical.

Unity Catalog object hierarchy

The securable objects are:

  • METASTORE: The top-level container for metadata. Each Unity Catalog metastore exposes a three-level namespace (catalog.schema.table) that organizes your data.

  • CATALOG: The first layer of the object hierarchy, used to organize your data assets.

  • SCHEMA: Also known as databases, schemas are the second layer of the object hierarchy and contain tables and views.

  • TABLE: The lowest level in the object hierarchy, tables can be external (stored in external locations in your cloud storage of choice) or managed tables (stored in a storage container in your cloud storage that you create expressly for Databricks).

  • VIEW: A read-only object created from one or more tables that is contained within a schema.

  • EXTERNAL LOCATION: An object that contains a reference to a storage credential and a cloud storage path that is contained within a Unity Catalog metastore.

  • STORAGE CREDENTIAL: An object that encapsulates a long-term cloud credential that provides access to cloud storage that is contained within a Unity Catalog metastore.

  • FUNCTION: A user-defined function that is contained within a schema.

  • SHARE: A logical grouping for the tables you intend to share using Delta Sharing. A share is contained within a Unity Catalog metastore.

  • RECIPIENT: An object that identifies an organization or group of users that can have data shared with them using Delta Sharing. These objects are contained within a Unity Catalog metastore.

  • PROVIDER: An object that represents an organization that has made data available for sharing using Delta Sharing. These objects are contained within a Unity Catalog metastore.

Inheritance model

Securable objects in Unity Catalog are hierarchical and privileges are inherited downward. The highest level object that privileges are inherited from is the catalog. This means that granting a privilege on a catalog or schema automatically grants the privilege to all current and future objects within the catalog or schema. Privileges that are granted on a Unity Catalog metastore are not inherited.

For example, the following command grants the SELECT privilege on all tables and views in any schema in the catalog main to the group finance:

GRANT SELECT ON CATALOG main TO finance;

Similarly, you can perform the grants on a schema for a smaller scope of access:

GRANT SELECT ON SCHEMA main.default TO finance;

The inheritance model provides an easy way to set up default access rules for your data. For example the following commands enable the machine learning team to create tables within a schema and read each other’s tables:

CREATE CATALOG ml;
CREATE SCHEMA ml.team_sandbox;
GRANT USE_CATALOG ON CATALOG ml TO ml_team;
GRANT USE_SCHEMA ON SCHEMA ml.team_sandbox TO ml_team;
GRANT CREATE TABLE ON SCHEMA ml.team_sandbox TO ml_team;
GRANT SELECT ON SCHEMA ml.team_sandbox TO ml_team;

Privilege types in Unity Catalog

The following table summarizes which privilege types apply to each securable object in the catalog:

Securable

Privileges

Metastore

CREATE CATALOG, CREATE EXTERNAL LOCATION, CREATE RECIPIENT, CREATE SHARE, CREATE PROVIDER

Catalog

ALL PRIVILEGES, CREATE SCHEMA, USE CATALOG

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

CREATE FUNCTION, CREATE TABLE, CREATE VIEW, EXECUTE, MODIFY, SELECT, USE SCHEMA

Schema

ALL PRIVILEGES, CREATE FUNCTION, CREATE TABLE, CREATE VIEW, 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

Table

ALL PRIVILEGES, SELECT, MODIFY

View

ALL PRIVILEGES, SELECT

External location

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

Storage credential

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

Function

ALL PRIVILEGES, EXECUTE

Share

SELECT (Can be granted to RECIPIENT)

Recipient

None

Provider

None

When you manage privileges on a metastore, you do not include the metastore name in a SQL command. Unity Catalog grants or revokes the privilege on the metastore attached to your workspace. For example, the following command grants a group named engineering the ability to create a catalog in the metastore attached to the workspace:

GRANT CREATE CATALOG ON METASTORE TO engineering

ALL PRIVILEGES

Applicable object types: CATALOG, EXTERNAL LOCATION, STORAGE CREDENTIAL, SCHEMA, FUNCTION, TABLE, VIEW

Used to grant or revoke all privileges applicable to the securable and its child objects without explicitly specifying them. This expands to all available privileges at the time permissions checks are made.

Note

This privilege is powerful when applied at higher levels in the hierarchy. For example, GRANT ALL PRIVILEGES ON CATALOG main TO analysts would give the analyst team all privileges on every object (schemas, tables, views, functions) in the catalog.

CREATE CATALOG

Applicable object types: Unity Catalog metastore

Allows a user to create a catalog in a Unity Catalog metastore.

CREATE EXTERNAL LOCATION

Applicable object types: Unity Catalog metastore, STORAGE CREDENTIAL

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

CREATE EXTERNAL TABLE

Applicable object types: EXTERNAL LOCATION, STORAGE CREDENTIAL

Allows a user to create external tables directly in your cloud tenant using an external location or storage credential. Databricks recommends granting this privilege on an external location rather than storage credential (since it’s scoped to a path, it allows more control over where users can create external tables in your cloud tenant).

CREATE FUNCTION

Applicable object types: SCHEMA

Allows a user to create a function in the schema. Since privileges are inherited, CREATE FUNCTION can also be granted on a catalog, which allows a user to create a function in any existing or future schema in the catalog.

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

CREATE MANAGED STORAGE

Applicable object types: EXTERNAL LOCATION

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

CREATE PROVIDER

Applicable object types: Unity Catalog metastore

Allows a user to create a Delta Sharing provider object in the metastore. A provider identifies an organization or group of users that have shared data using Delta Sharing. Provider creation is performed by a user in the recipient’s Databricks account. See Share data securely using Delta Sharing.

CREATE RECIPIENT

Applicable object types: Unity Catalog metastore

Allows a user to create a Delta Sharing recipient object in the metastore. A recipient identifies an organization or group of users that can have data shared with them using Delta Sharing. Recipient creation is performed by a user in the provider’s Databricks account. See Share data securely using Delta Sharing.

CREATE SCHEMA

Applicable object types: CATALOG

Allows a user to create a schema. The user must also have the USE CATALOG privilege on the catalog.

CREATE SHARE

Applicable object types: Unity Catalog metastore

Allows a user to create a share in the metastore. A share is a logical grouping for the tables you intend to share using Delta Sharing

CREATE TABLE

Applicable object types: SCHEMA

Allows a user to create a table in the schema. Since privileges are inherited, CREATE TABLE can also be granted on a catalog, which allows a user to create a table in any existing or future schema in the catalog.

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

CREATE VIEW

Applicable object types: SCHEMA

Allows a user to create a view in the schema. Since privileges are inherited, CREATE VIEW can also be granted on a catalog, which allows a user to create a view in any existing or future schema in the catalog.

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

EXECUTE

Applicable object types: FUNCTION

Allows a user to invoke a user defined function, if the user also has USE CATALOG on its parent catalog and USE SCHEMA on its parent schema.

Since privileges are inherited, you can grant a user the EXECUTE privilege on a catalog or schema, which automatically grants the user the EXECUTE privilege on all current and future functions in the catalog or schema.

MODIFY

Applicable object types: TABLE

Allows a user to add, update, and delete data to or from the table if the user also has SELECT on the table as well as USE CATALOG on its parent catalog and USE SCHEMA on its parent schema.

Since privileges are inherited, you can grant a user the MODIFY privilege on a catalog or schema, which automatically grants the user the MODIFY privilege on all current and future tables in the catalog or schema.

READ FILES

Applicable object types: EXTERNAL LOCATION, STORAGE CREDENTIAL

Allows a user to read files directly from your cloud object storage. Databricks recommends granting this privilege on an external location rather than storage credential (since it’s scoped to a path it allows more control over where users can read data from).

SELECT

Applicable object types: TABLE, VIEW, SHARE

If applied to a table or view, allows a user to select from the table or view, if the user also has USE CATALOG on its parent catalog and USE SCHEMA on its parent schema. If applied to a share, allows a recipient to select from the share.

Since privileges are inherited, you can grant a user the SELECT privilege on a catalog or schema, which automatically grants the user SELECT privilege on all current and future tables, and views in the catalog or schema.

USE CATALOG

Applicable object types: CATALOG

This privilege does not grant access to the catalog itself, but is needed for a user to interact with any object within the catalog. For example, to select data from a table, users need to have the SELECT privilege on that table and USE CATALOG privileges on its parent catalog as well as USE SCHEMA privileges on its parent schema.

This is useful for allowing catalog owners to be able to limit how far individual schema and table owners can share data they produce. For example, a table owner granting SELECT to another user does not allow that user read access to the table unless they also have been granted USE CATALOG privileges on its parent catalog as well as USE SCHEMA privileges on its parent schema.

USE SCHEMA

Applicable object types: SCHEMA

This privilege does not grant access to the schema itself, but is needed for a user to interact with any object within the schema. For example, to select data from a table, users need to have the SELECT privilege on that table and USE SCHEMA on its parent schema as well as USE CATALOG on its parent catalog.

Since privileges are inherited, you can grant a user the USE SCHEMA privilege on a catalog, which automatically grants the user the USE SCHEMA privilege on all current and future schemas in the catalog.

WRITE FILES

Applicable object types: EXTERNAL LOCATION, STORAGE CREDENTIAL

Allows a user to write files directly into your cloud object storage. Databricks recommends granting this privilege on an external location rather than storage credential (since it is scoped to a path it allows more control over where users can write data to).