Unity Catalog API 2.1 Specification

Purpose and Scope

This document gives a compact specification of the Unity Catalog (UC) 2.1 API, focusing on the messages and endpoints constituting the UC’s Public API. The Delta Sharing API is also within scope.

The following areas are not covered by this document:

Terminology

User Types

All users that access Unity Catalog APIs must be account-level users. They must also be added to the relevant Databricks Workspace (in order to obtain a PAT token used to access the UC API server).

Metastore Admins

Metastore Admins can manage the privileges for all securable objects inside a metastore, such as who can create catalogs or query a table. For more details on the Metastore admin role, read Manage privileges in Unity Catalog

Account Admins

An Account Admin is an account-level user with the “Account Owner” role configured in the Accounts Console. For more details, read Administrator privileges in Unity Catalog.

Client Types

The Unity Catalog's API server is accessible through external clients. These clients authenticate with "external" tokens (for example, PAT tokens obtained from a Workspace). This is an important distinction. You must first obtain a Personal Access Token (PAT) to access the Unity Catalog API from an external client. This includes using the Databricks CLI's unity-catalog commands to access the UC API.

API  Conventions

API Usage Notes

Common Data Models

Properties

The Catalog, Schema and Table objects each have a properties field, which is an opaque list of key-value pairs. This list allows for future extension or customization of the object’s configuration.

Field Name

Type

Description

properties

Map[string,string]

Extensible catalog properties

Public APIs

The API endpoints in this section are for use by external clients. These API endpoints enforce permissions on Unity Catalog objects so that the client user only has access to objects to which they have permission.

Metastore CRUD API

Object Models

DeltaSharingScope

The supported values of the delta_sharing_scope field (within a MetastoreInfo) are the following strings:


MetastoreInfo:

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of metastore

storage_root

string (url)

REQ

ERR

Metastore storage root path. On creation, the new metastore’s ID (UUID) is appended to the provided storage_root, so the output storage_root is not the same as the input storage_root.

default_data_access_config_id
[DEPRECATED]

string (uuid)

IGN

OPT

Unique identifier of default DataAccessConfiguration for creating access tokens for objects in Metastore. Now replaced by storage_root_credential_id.

storage_root_credential_id

string (uuid)

IGN

OPT

Unique identifier of the Storage Credential used by default to access the storage_root area of cloud storage.

owner

string

IGN[1]

OPT

Username/groupname of Metastore owner

delta_sharing_enabled [DEPRECATED]

bool

IGN

OPT

Whether delta sharing is enabled for this Metastore (default: false)

delta_sharing_scope

String (DeltaSharingScope)

IGN

OPT

Delta Sharing Scope (default: INTERNAL).

delta_sharing_recipient_token_lifetime_in_seconds

int32

IGN

OPT

The lifetime of delta sharing recipient token in seconds (no default; must be specified when delta_sharing_scope is set to INTERNAL_AND_EXTERNAL).

delta_sharing_organization_name

string

IGN

OPT

The organization name of a Delta Sharing entity. The name will be used in Databricks-to-Databricks Delta Sharing as the official name.

privilege_model_version

string

IGN

OPT

Privilege model version. This is of the form major.minor.

Output-only:

metastore_id

string (uuid)

IGN

IGN

Unique identifier for metastore

cloud

string

IGN

IGN

Cloud vendor of Metastore home shard, e.g. “aws”, “azure

region

string

IGN

IGN

Cloud region of the Metastore home shard, e.g. “us-west-2”, “westus

global_metastore_id

string

IGN

IGN

Globally unique metastore ID across clouds and regions.  E.g., “aws:us-east-1:8dd1e334-c7df-44c9-a359-f86f9aae8919

created_at

int64

IGN

IGN

Date of metastore creation

created_by

string

IGN

IGN

Username of metastore creator

updated_at

int64

IGN

IGN

Date of last update to metastore

updated_by

string

IGN

IGN

Username of user who last modified metastore

DeleteMetastoreOpts:

Field Name

Type

Req?

Description

force

bool

OPT

Default: false. When false, the deletion fails when the specified Metastore is non-empty (contains non-deleted Catalogs, DataAccessConfigurations, Shares or Recipients). When set to true, the specified Metastore is deleted regardless of its contents.  

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/metastores

createMetastore

MetastoreInfo
(partial)

MetastoreInfo

GET

<prefix>/metastores

listMetastores

None

Array[MetastoreInfo]

GET

<prefix>/metastores/:id

getMetastore

None

MetastoreInfo

PATCH

<prefix>/metastores/:id

updateMetastore

MetastoreInfo
(partial)

MetastoreInfo

DELETE

<prefix>/metastores/:id

deleteMetastore

DeleteMetastoreOpts

None

Endpoint Behavior Notes

Authorization

All Metastore Admin CRUD API endpoints are restricted to Metastore Admins.

listMetastores Output

The listMetastores endpoint does not list all Metstores that exist in the customer account. Instead it restricts the list by what the Workspace (as determined by the client’s PAT token) can access. Effectively, this means that the output will either be an empty list (if no Metastore is assigned to the Workspace) or a list containing a single Metastore (the  one assigned to the Workspace).

Metastore Summary API

The metastore_summary endpoint provides a simple means for clients to determine the metastore_id of the Metastore assigned to the workspace inferred from the user’s authentication token.

Object Model

MetastoreSummaryInfo [DEPRECATED]

Field Name

Type

Description

metastore_id

string (uuid)

Unique identifier for metastore

name

string

Name of metastore

storage_root_credential_id

string (uuid)

Unique identifier of the Storage Credential to use for accessing table data in cloud storage

default_data_access_config_id
[DEPRECATED]

string (uuid)

Unique identifier of the DAC for accessing table data in cloud storage

cloud

string

Cloud vendor of Metastore home shard, e.g. “aws”, “azure

region

string

Cloud region of the Metastore home shard, e.g. “us-west-2”, “westus

global_metastore_id

string

Globally unique metastore ID across clouds and regions.  E.g., “aws:us-east-1:8dd1e334-c7df-44c9-a359-f86f9aae8919

RPC Endpoints

HTTP Method

URI

Endpoint Name

Output

GET

<prefix>/metastore_summary

getMetastoreSummary

MetastoreSummaryInfo [DEPRECATED]

Metastore Assignment API

Object Models

MetastoreAssignment:

Field Name

Type

Create

Update

Delete

Description

metastore_id

String (uuid)

REQ

OPT

REQ

Unique identifier for metastore

default_catalog_name

string

REQ

OPT

IGN

Default catalog used for this assignment

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

PUT

<prefix>/workspaces/
:workspace_id/metastore

createMetastoreAssignment

MetastoreAssignment

None

PATCH

<prefix>/workspaces/
:workspace_id/metastore

updateMetastoreAssignment

MetastoreAssignment

None

DELETE

<prefix>/workspaces/
:workspace_id/metastore

deleteMetastoreAssignment

MetastoreAssignment

None

Inputs

The workspace_id path parameter is an int64 number, the unique identifier of the workspace.

Endpoint Behavior Notes

If an assignment on the same workspace_id already exists, it will be overwritten by the new metastore_id and default_catalog_name.

This endpoint can be used to update metastore_id and / or default_catalog_name for a specified workspace, if workspace is already assigned a Metastore.

Authorization

The createMetastoreAssignment and deleteMetastoreAssignment endpoints require that the client user is an Account Administrator.

The updateMetastoreAssignment endpoint requires that either:

  1. If updating the metastore_id: the​​ client user must be an Account Administrator
  2. Otherwise, the client user must be a Workspace Administrator

Storage Credential CRUD API

Object Models

AwsIamRole

Field Name

Type

Create

Update

Description

role_arn

string

REQ

OPT

The Amazon Resource Name (ARN) of the AWS IAM role for S3 data access

Output-only:

unity_catalog_iam_arn

string

IGN

IGN

The Amazon Resource Name (ARN) of the AWS IAM user managed by Databricks. This is the identity that is going to assume the AWS IAM role.

external_id

string

IGN

IGN

The external ID used in role assumption to prevent confused deputy problems.

AzureServicePrincipal

Field Name

Type

Create

Update

Description

directory_id

string

REQ

OPT

The directory ID corresponding to the Azure Active Directory (AAD) tenant of the application

application_id

string

REQ

OPT

The application ID of the application registration within the referenced AAD tenant

client_secret

string

REQ

OPT

The client secret generated for the above app ID in AAD. This field is redacted on output.

GcpServiceAccountKey

Field Name

Type

Create

Update

Description

email

string

REQ

OPT

The email of the service account

private_key_id

string

REQ

OPT

The ID of the service account's private key

private_key

string

REQ

OPT

The service account's RSA private key. This field is redacted on output.


DeleteStorageCredentialOpts:

Field Name

Type

Req?

Description

force

bool

OPT

Default: false. When false, the deletion fails when the specified Storage Credential has dependent External Locations or external tables. When set to true, the specified Storage Credential is deleted regardless of its dependencies.  

StorageCredentialInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Storage Credential (must be unique within the parent Metastore)

comment

string

OPT

OPT

User-supplied free-form text

owner

string

IGN[2]

OPT

Username/groupname of Storage Credential owner

skip_validation

bool

OPT

OPT

Specifies whether a Storage Credential with the specified configuration should be tested (for access to cloud storage) before the object is created/updated. Default: false
Note: this is an input-only field

Credential details – one of:

aws_iam_role

AwsIamRole

REQ

OPT

Credential details for AWS

azure_service_principal

AzureServicePrincipal

REQ

OPT

Credential details for Azure

gcp_service_account_key

GcpServiceAccountKey

REQ

OPT

Credential details for GCP

Output-only:

id

string (uuid)

IGN

IGN

Unique identifier of the Storage Credential

metastore_id

string (uuid)

IGN

IGN

Unique identifier of the parent Metastore

created_at

int64

IGN

IGN

Date of Storage Credential creation

created_by

string

IGN

IGN

Username of Storage Credential creator

updated_at

int64

IGN

IGN

Date of last update to Storage Credential

updated_by

string

IGN

IGN

Username of user who last updated Storage Credential

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/storage-credentials

createStorage
Credential

StorageCredentialInfo
(partial)

StorageCredentialInfo

GET

<prefix>/storage-credentials

listStorage
Credentials

None

Array[StorageCredentialInfo]

GET

<prefix>/storage-credentials/:name

getStorage
Credential

None

StorageCredentialInfo

PATCH

<prefix>/storage-credentials/:name

updateStorageCredential

StorageCredentialInfo
(partial)

StorageCredentialInfo

DELETE

<prefix>/storage-credentials/:name

deleteStorageCredential

DeleteStorageCredentialOpts

None

Endpoint Behavior Notes

Authorization

The createStorageCredential endpoint requires that the user is an Account admin.

The getStorageCredential endpoint requires that either the user:

  1. is a Metastore admin or Account admin
  2. is the owner of the Storage Credential
  3. has some privilege on the Storage Credential

The  listStorageCredentials endpoint returns either:

  1. all Storage Credentials (within the current Metastore) if the user is a Metastore admin or Account admin
  2. all Storage Credentials (within the current Metastore) for which the caller is the owner or has some privilege

The updateStorageCredential endpoint requires either:

  1. the user is an owner of the Storage Credential, an Account Admin, or a metastore admin if its owner is changed
  2. the user is an Account Admin for all other updates (such as updates to the name, comment, credential, etc. properties for the credential)

The deleteStorageCredential endpoint requires that the user is an owner of the Storage Credential or an Account admin.

External Location CRUD API

Object Models

DeleteExternalLocationOpts

Field Name

Type

Req?

Description

force

bool

OPT

Default: false. When false, the deletion fails when the specified External Location has dependent external tables. When set to true, the specified External Location is deleted regardless of its dependencies.  


ListFilesReq

Field Name

Type

Req?

Description

url

string (url)

REQ

Path URL to use to list files

credential_name

string

OPT

Name of Storage Credential to use for accessing the URL

max_results

int32

OPT

Limit on number of results to return

FileInfo

Field Name

Type

Description

path

string (url)

Path URI of the storage object

name

string

Name of the object

size

int64

Size in bytes

mtime

int64

Modification time, based on unix epoch

is_dir

bool

Whether the object is a directory (or a file)

ListFilesResp

Field Name

Type

Description

files

Array[FileInfo]

List of FileInfo objects, one per file/dir

ExternalLocationInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of External Location (must be unique within the parent Metastore)

comment

string

OPT

OPT

User-supplied free-form text

owner

string

IGN[3]

OPT

Username/groupname of External Location owner

url

string (url)

REQ

OPT

Path URL in cloud storage, of the form:

AWS: "s3://bucket-host/[bucket-dir]"
Azure: "abfss://host/[path]"
GCP: "gs://bucket-host/[path]"

credential_name

string

REQ

OPT

Name of the Storage Credential to use with this External Location

read_only

bool

OPT

OPT

Whether the External Location is read-only (default: false)

Input-only (for Update):

force

bool

N/A

OPT

Force update even if changing url invalidates dependent external tables (default: false)

skip_validation

bool

N/A

OPT

Whether to skip Storage Credential validation during update of the External Location (default: false)

Output-only:

credential_id
[DEPRECATED]

string (uuid)

IGN

IGN

Unique identifier of the External Location

metastore_id

string (uuid)

IGN

IGN

Unique identifier of the parent Metastore

created_at

int64

IGN

IGN

Date of External Location creation

created_by

string

IGN

IGN

Username of External Location creator

updated_at

int64

IGN

IGN

Date of last update to External Location

updated_by

string

IGN

IGN

Username of user who last updated External Location

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/external-locations

createExternalLocation

ExternalLocation
Info
(partial)

ExternalLocationInfo

GET

<prefix>/external-locations

listExternal
Locations

None

Array[ExternalLocationInfo]

GET

<prefix>/external-locations/:name

getExternal
Location

None

ExternalLocationInfo

PATCH

<prefix>/external-locations/:name

updateExternalLocation

ExternalLocation
Info
(partial)

ExternalLocationInfo

DELETE

<prefix>/external-locations/:name

deleteExternalLocation

DeleteExternal
LocationOpts

None

GET

<prefix>/files

listFiles

ListFilesReq

ListFilesResp

Endpoint Behavior Notes

External Location URL Constraints

The storage url for an External Location must not conflict with other External Locations or external Tables. Specifically,

Authorization

The createExternalLocation endpoint requires that either the user

  1. is a Metastore admin
  2. has CREATE EXTERNAL LOCATION privilege on the Metastore

The getExternalLocation endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the External Location
  3. has some privilege on the External Location

The  listExternalLocations endpoint returns either:

  1. all External Locations (within the current Metastore), when the user is a Metastore admin
  2. all External Locations for which the user is the owner or the user has some privilege

The updateExternalLocation endpoint requires either:

  1. the user is the owner of the External Location
  2. the user is a Metastore admin and only the owner field is changed

The deleteExternalLocation endpoint requires that the user is an owner of the External Location.

Catalog CRUD API

Object Models

CatalogInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Catalog relative to parent metastore

comment

string

OPT

OPT

User-supplied free-form text

properties

Map[string,string]

OPT

OPT

Extensible Catalog properties

owner

string

IGN[4]

OPT

Username/groupname of Catalog owner

provider_name

string

OPT

IGN

For Delta Sharing Catalogs: the name of the delta sharing provider

share_name

string

OPT

IGN

For Delta Sharing Catalogs: the name of the share under the share provider

Output-only:

metastore_id

string (uuid)

IGN

IGN

Unique identifier of the parent Metastore

created_at

int64

IGN

IGN

Date of Catalog creation

created_by

string

IGN

IGN

Username of Catalog creator

updated_at

int64

IGN

IGN

Date of last update to Catalog

updated_by

string

IGN

IGN

Username of user who last updated Catalog

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/catalogs

createCatalog

CatalogInfo
(partial)

CatalogInfo

GET

<prefix>/catalogs

listCatalogs

None

Array[CatalogInfo]

GET

<prefix>/catalogs/:name

getCatalog

None

CatalogInfo

PATCH

<prefix>/catalogs/:name

updateCatalog

CatalogInfo
(partial)

CatalogInfo

DELETE

<prefix>/catalogs/:name

deleteCatalog

None

None

Endpoint Behavior Notes

Authorization

The createCatalog endpoint requires that either the user

  1. is a Metastore admin
  2. has CREATE CATALOG privilege on the Metastore

When creating a Delta Sharing Catalog, the user needs to also be an owner of the Provider.

The getCatalog endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Catalog
  3. has the USAGE privilege on the Catalog

The  listCatalogs endpoint returns either:

  1. all Catalogs (within the current Metastore), when the user is a Metastore admin
  2. all Catalogs (within the current Metastore) for which the user is the owner or the user has the USAGE privilege

In general, the updateCatalog endpoint requires either:

  1. the user is the owner of the Catalog
  2. the user is a Metastore admin and only the owner field is changed

In the case that the Catalog name is changed, updateCatalog requires that the user is both the Catalog owner and a Metastore admin.

The deleteCatalog endpoint requires that the user is an owner of the Catalog.

Schema CRUD API

Object Models

SchemaInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Schema relative to parent catalog

catalog_name

string

REQ

IGN

Name of parent Catalog

comment

string

OPT

OPT

User-supplied free-form text

owner

string

IGN[5]

OPT

Username/groupname of Schema owner

properties

Map[string,
   string]

OPT

OPT

Extensible Schema properties

Output-only:

metastore_id

string (uuid)

IGN

IGN

Unique identifier of the parent Metastore

full_name

string

IGN

IGN

Fully-qualified name of Schema as <catalog>.<schema>

created_at

int64

IGN

IGN

Date of Schema creation

created_by

string

IGN

IGN

Username of Schema creator

updated_at

int64

IGN

IGN

Date of last update to Schema

updated_by

string

IGN

IGN

Username of user who last updated Schema

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/schemas

createSchema

SchemaInfo
(partial)

SchemaInfo

GET

<prefix>/schemas[?<q_args>]

listSchemas

q_args

Array[SchemaInfo]

GET

<prefix>/schemas/:full_name

getSchema

None

SchemaInfo

PATCH

<prefix>/schemas/:full_name

updateSchema

SchemaInfo
(partial)

SchemaInfo

DELETE

<prefix>/schemas/:full_name

deleteSchema

None

None

Inputs

q_args:

Field Name

Type

REQ/OPT

Description

catalog_name

string

REQ

Name of the parent catalog

Endpoint Behavior Notes

Authorization

All *Schema endpoints require that the user have access to the parent Catalog. This means the user either

  1. is a Metastore admin
  2. is the owner of the parent Catalog
  3. has the USAGE privilege on the parent Catalog

All of the requirements below are in addition to this requirement of access to the parent Catalog.

The createSchema endpoint requires that the user either

  1. is a Metastore admin
  2. has the CREATE privilege on the parent Catalog

The getSchema endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Schema
  3. has the USAGE privilege on the Schema

The  listSchemas endpoint returns either:

  1. all Schemas (within the current Metastore and parent Catalog), when the user is either a Metastore admin or an owner of the parent Catalog
  2. all Schemas (within the current Metastore and parent Catalog) for which the user is the owner or the user has the USAGE privilege

In general, the updateSchema endpoint requires either:

  1. the user is the owner of the Schema
  2. the user is a Metastore admin and only the owner field is changed

In the case that the Schema name is changed, updateSchema also requires that the user have the CREATE privilege on the parent Catalog (or be a Metastore admin).

The deleteSchema endpoint requires that the user is an owner of the Schema or an owner of the parent Catalog.

Table CRUD API

Object Model

TableInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Table relative to parent Schema

catalog_name

string

REQ

IGN

Name of parent Catalog

schema_name

string

REQ

IGN

Name of parent Schema relative to parent Catalog

table_type

string

REQ

IGN

Distinguishes a view vs. managed/external Table

data_source_format

string

REQ*

OPT

See Data Source Format spec

columns

Array[ColumnInfo]

REQ

OPT

Sequence of Table columns

storage_location

string

REQ*

REQ*

URL of storage location for Table data (* REQ for EXTERNAL Tables. For Managed Tables, if the path is provided it needs to be a Staging Table path that has been generated through the Sttaging Table API, otherwise should be empty)

storage_credential_name

string

OPT

IGN

For EXTERNAL Tables only: the name of storage credential to use (may not be changed via UpdateTable endpoint).

view_definition

string

REQ for View

OPT

SQL text defining the view (for table_type == "VIEW")

sql_path

string

OPT

OPT

List of schemes whose objects can be referenced without qualification (ref)

comment

string

OPT

OPT

User-supplied free-form text

owner

string

IGN[6]

OPT

Username/groupname of Table owner

properties

Map[string,string]

OPT

OPT

Extensible Table properties

Output-only:

metastore_id

string (uuid)

IGN

IGN

Unique identifier of the parent Metastore

full_name

string

IGN

IGN

Fully-qualified name of Table as <catalog>.<schema>.<table>

data_access_configuration_id
[DEPRECATED]

string (uuid)

IGN

IGN

Unique identifier of  DataAccessConfig to use to access table data.

created_at

int64

IGN

IGN

Date of Table creation

created_by

string

IGN

IGN

Username of Table creator

updated_at

int64

IGN

IGN

Date of last update to Table

updated_by

string

IGN

IGN

Username of user who last updated Table


REQ* = Required for External and Managed Tables


Table Type

The supported values of the table_type field (within a TableInfo) are the following strings:

Column Type Name

The supported values of the type_name field (within a ColumnInfo) are the following strings:

Data Source Format

External tables are supported in multiple data source formats. The string constants identifying these formats are:

ColumnInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

User-visible name of column

type_name

string

REQ

OPT

Name of (outer) type; see Column Type  Name above

type_text

string

REQ

OPT

Column type spec (with metadata) as SQL text

type_json

string

REQ

OPT

Column type spec (with metadata) as JSON string

type_precision

int32

OPT

OPT

Digits of precision; applies to DECIMAL columns

type_scale

int32

OPT

OPT

Digits to right of decimal; applies to DECIMAL columns

type_interval_type

string

OPT

OPT

Format of INTERVAL columns

position

int32

REQ

OPT

Ordinal position of column, starting at 0.

comment

string

OPT

OPT

User-supplied free-form text

nullable

bool

OPT

OPT

Whether field is nullable (Default: true)

partition_index

int16

OPT

OPT

Partition ID

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/tables

[Experimental] createTable


This endpoint is currently experimental and unstable. When scripting create table operations, use the DBSQL API.

TableInfo
(partial)

TableInfo

GET

<prefix>/tables[?<q_args>]

listTables

q_args

TableList

GET

<prefix>/tables/:full_name

getTable

None

TableInfo

PATCH

<prefix>/tables/:full_name

[Experimental] updateTable

This endpoint is currently experimental and unstable. When scripting create table operations, use the DBSQL API.

TableInfo
(partial)

TableInfo

DELETE

<prefix>/tables/:full_name

deleteTable

None

None

GET

<pe_prefix>/tables/:full_name

privilegedGetTable

None

TableInfo

Inputs

q_args:

Field Name

Type

REQ/OPT

Description

catalog_name

string

REQ

Name of the parent catalog

schema_name

string

REQ

Name of the parent schema relative to its parent catalog

Both the catalog_name and schema_name arguments to the listTables endpoint are required. To list Tables in multiple Schemas (within the same Catalog) in a paginated, “bulk” fashion, see the listTableSummaries API below.

Endpoint Behavior Notes

Authorization

The [Experimental] createTable endpoint requires that the user meets all of the following requirements:

  1. has ownership or the USAGE privilege on both the parent Catalog and Schema (regardless of Metastore admin status)
  2. has ownership or the CREATE privilege on the parent Schema

If the new table has table_type of “EXTERNAL” the user must either be a Metastore admin or meet the permissions requirement of the Storage Credential and/or External Location used by the External Table.

The getTable endpoint requires that the user either is a Metastore admin or meets all of the following requirements:

  1. has ownership or the USAGE privilege on both the parent Catalog and Schema
  2. has ownership or the SELECT privilege on the requested Table

The  listTables endpoint returns either:

  1. all Tables (within the current Metastore and parent Catalog and Schema), when the user is a Metastore admin
  2. all Tables (within the current Metastore and parent Catalog and Schema) for which the user has ownership or the SELECT privilege, provided that the user also has ownership or the USAGE privilege on both the parent Catalog and Schema

In general, the [Experimental] updateTable endpoint requires both of the following:

  1. the user has either ownership or the USAGE privilege on both the parent Catalog and parent Schema
  2. the user is the owner of the Table or the user is a Metastore admin and only the owner field is changed

In the case that the Table name is changed, [Experimental] updateTable also requires that the user have the CREATE privilege on the parent Schema (even if the user is a Metastore admin).

In the case that the Table has table_type of “VIEW” and the owner field is being changed, the [Experimental] updateTable endpoint requires that the user is a member of the new owner.

The deleteTable endpoint requires that the user either

  1. is an owner of the parent Catalog
  2. has the USAGE privilege on the parent Catalog and is an owner of the parent Schema
  3. has the USAGE privilege on the parent Catalog and Schema and is owner of the Table

ListTableSummaries API

Object Models

TableSummariesReq

Field Name

Type

REQ/OPT

Description

catalog_name

string

REQ

Name of parent Catalog for Schemas and Tables of interest

schema_name_pattern

string

OPT

A SQL LIKE pattern (supporting % and _) specifying names of Schemas of interest

table_name_pattern

string

OPT

A SQL LIKE pattern (supporting % and _) specifying names of Tables of interest

max_results

int32

OPT

Maximum number of tables to return (i.e., the page length); defaults to 1000

page_token

string

OPT

Opaque token to send for the next page of results

TableSummary

Field Name

Type

Description

full_name

string

Fully-qualified name of Table , of the form
<
catalog>.<schema>.<table>

table_type

string

Distinguishes a view vs. managed/external Table

TableSummariesResp

Field Name

Type

Description

tables

Array[TableSummary]

List of Table Summaries

next_page_token

string

Opaque token to use to retrieve the next page of results

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/table-summaries

listTableSummaries

TableSummariesReq

TableSummariesResp

Endpoint Behavior Notes

Authorization

The  listTables endpoint returns either:

  1. TableSummary’s for all Tables (within the current Metastore and parent Catalog and Schema), when the user is a Metastore admin
  2. TableSummary’s for all Tables and Schemas (within the current Metastore and parent Catalog) for which the user has ownership or the SELECT privilege on the Table and ownership or USAGE privilege on the Schema, provided that the user also has ownership or the USAGE privilege on the parent Catalog

Permissions API

Terminology and Permissions Management Model

The Databricks Permissions API manages the Permission Level (e.g., "CAN_USE", "CAN_MANAGE"), a scalar value that users have for the various object types (Notebooks, Jobs, Tokens, etc.).  For the objects managed by Unity Catalog, principals (users or groups) may have a collection of permissions that do not organize consistently into levels, as they are independent abilities. For example, a given user may have the ability to MODIFY a Schema but that ability does not imply the user’s ability to CREATE Tables within that Schema, nor vice-versa.

Though the nomenclature may not be industry-standard, we define the following terms:

In this way, we can speak of a securable’s permissions, or a user’s privileges on that securable (object).

SQL Object Privileges

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 objects within the catalog. Similarly, privileges granted on a schema are inherited by all current and future objects within that schema.

See Unity Catalog privileges and securable objects for the supported privilege values on each securable object.

Object Models

PrivilegeAssignment

The PrivilegesAssignment type maps a single principal to the privileges assigned to that principal.

Field Name

Type

Description

principal

string

The username (email address) or group name

privileges

Array[string]

List of privileges assigned to the principal

PermissionsList

The PermissionsList message type is used to list all permissions on a given securable. It maps each principal to their assigned privileges.

Field Name

Type

Description

privilege_assignments

Array[PrivilegeAssignment]

List of all permissions (configured for a securable), mapping all specified principals to their associated privileges.

An example PermissionsList:

{
  "privilege_assignments": [
   {
     "principal": "
username@examplesemail.com",
     "privileges": ["SELECT"]
   },`
   {
     "principal": "eng-data-security",
     "privileges": ["SELECT","MODIFY","CREATE"]
   },
   {
     "principal": "users",
     "privileges": ["USE SCHEMA", "USE CATALOG"]
   }
 ]
}

PermissionsChange

The updatePermissions (PATCH) endpoint allows the client to specify a set of incremental changes to make to a securable’s permissions.

The PermissionsChange type specifies the privileges to add to and/or remove from a single principal.

Field Name

Type

Description

principal

string

The username (email address) or group name

add

Array[string]

List of privileges to add for the principal

remove

Array[string]

List of privileges to remove from the principal

PermissionsDiff

The PermissionsDiff message type specifies a list of changes to make to a securable's permissions.

Field Name

Type

Description

changes

Array[PermissionsChange]

List of changes to make to a securable’s permissions

An example PermissionsDiff:

{
 "changes": [

    {

      "principal": "username@examplesemail.com",
     "add": ["SELECT"],
     "remove": ["MODIFY"]
   },
   {
     "principal": "eng-data-security",
     "remove": ["CREATE"]
   },
   {
     "principal": "users",
     "add": ["USE SCHEMA", "USE CATALOG"]
   }

  ]

}


Changing Ownership

A special case of a permissions change is a change of ownership. This corresponds to the SQL command “ALTER <securable_type> <securable_name> OWNER to <principal>” and is subject to the restrictions described in the Governance Model.

Changing ownership is done by invoking the update<Securable> endpoint with input that includes the “owner” field containing the username/groupname of the new owner. To be clear, this ownership change does
not involve calling the Permissions API.

In the near future, there may be an “OWN” privilege added to the privileges supported by UC.


RPC Endpoints

The Unity Catalog Permissions APIs applies to multiple securable types, with the following securable identifier (sec_full_name) fields:

sec_type

sec_id field

Description

metastore

id

The metastore ID

catalog

name

The catalog name

schema

full_name

The full name of the schema (<catalog>.<schema>)

table

full_name

The full name of the table (<catalog>.<schema>.<table>)

storage-credential

name

The storage credential name

external-location

name

The external location name

view

full_name

The full name of the view (<catalog>.<schema>.<view>)

function

name

The full name of the function (<catalog>.<schema>.<function>)

 

HTTP Method

URI

Endpoint Name

Input

Output

GET

<prefix>/permissions/<sec_type>/
 <sec_full_name>[?q_args]

getPermissions

q_args

PermissionsList

PATCH

<prefix>/permissions/<sec_type>/
 <sec_full_name>

updatePermissions

PermissionsDiff

PermissionsList

PUT

<prefix>/permissions/<sec_type>/
 <sec_full_name>

PermissionsList

None

Examples:
GET /api/2.1/unity-catalog/permissions/catalog/some_cat
PUT /api/2.1/unity-
catalog/permissions/table/some_cat.other_schema.my_table

Inputs

q_args:

Field Name

Type

REQ/OPT

Description

principal

string

OPT

Principal of interest (only return permissions for this user/group)

Authorization, Error Responses

The Data Governance Model describes the details on GRANT, REVOKE and SHOW GRANT commands, and these correspond to the adding, removing of privileges along with the fetching of permissions from the getPermissions endpoint. The output and error behavior for the API endpoints is:

 {
   "error_code": "
UNAUTHORIZED",
   "message": "Users can only grant or revoke schema and table permissions."
}

 User-Info API

Object Models

GetMyInfoResp:

Field Name

Type

Description

is_metastore_admin

bool

Flag indicating whether or not the user is a Metastore administrator

GetMyGroupsResp:

Field Name

Type

Description

group_names

Array[string]

List of group names

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

GET

<prefix>/user-info/me[?<q_args>]

getMyInfo

q_args

GetMyInfoResp

GET

<prefix>/user-info/my-groups

getMyGroups

GetMyGroupsReq

GetMyGroupsResp

Inputs

q_args:

Field Name

Type

REQ/OPT

Description

for_account_level

bool

OPT

Whether the groups returned correspond to the account-level or workspace-level group memberships

Share CRUD API (Delta Sharing)

Object Models

ShareInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Share relative to parent metastore

comment

string

OPT

OPT

User-supplied free-form text

objects

Array[ShareDataObject]

IGN

OPT

A list of shared data objects within the Share

owner

string

IGN[7]

OPT

Username/groupname of Share owner

Output-only:

created_at

int64

IGN

IGN

Date of Share creation

created_by

string

IGN

IGN

Username of Share creator

updated_at

int64

IGN

IGN

Date of last update to Share

updated_by

string

IGN

IGN

Username of user who last updated Share

ShareDataObject

Field Name

Type

Create

Update

Description

name

string

IGN

OPT

A fully qualified name that uniquely identifies a data object. For example, a table's fully qualified name is in the format of `<catalog>.<schema>.<table>`.

comment

string

IGN

OPT

User-supplied free-form text

shared_as

string

IGN

OPT

A user-provided new name for the data object within the share. If this new name is not provided, the object's original name will be used as the `shared_as` name. The `shared_as` name must be unique within a Share.

For tables, the new name must follow the format of `<schema>.<table>`.

partition_specification

PartitionSpecification

IGN

OPT

Defines the format of partition filtering specification for shared tables.

It consists of a list of Partitions which in turn include a list of PartitionValues.

cdf_enabled

bool

IGN

OPT

Whether to enable Change Data Feed (cdf) or indicate if cdf is enabled on the shared object.

start_version

int64

IGN

OPT

The start version associated with the object for cdf.

This allows data providers to control the lowest object version that is accessible by clients.

If specified, clients can query snapshots or changes for versions >= start_version.

If not specified, clients can only query starting from the version of the object at the time it was added to the share.

NOTE: The start_version should be <= the "current" version of the object.

Output-only:

added_at

int64

IGN

IGN

Date of table add to share

added_by

string

IGN

IGN

Username of user who added table to share

data_object_type

string

IGN

IGN

Type of data object.

Currently, the only supported type is "TABLE".

PartitionSpecification

Field Name

Type

Create

Update

Description

partitions

Array[Partition]

IGN

OPT

Partitions have OR logical relationship

Partition

Field Name

Type

Create

Update

Description

values

Array[PartitionValues]

IGN

OPT

Partition Values have AND logical relationship

PartitionValues

Field Name

Type

Create

Update

Description

name

string

IGN

OPT

The name of the partition column. Must be distinct within a single partition

value

string

IGN

OPT

The value of the partition column. When this value is not set, it means `null` value.

op

string

IGN

OPT

The operator to apply for the value. Can be "EQUAL" or "LIKE".

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/shares

createShare

ShareInfo
(partial)

ShareInfo

GET

<prefix>/shares

listShares

None

Array[ShareInfo]

GET

<prefix>/shares/:name

getShare

None

ShareInfo

PATCH

<prefix>/shares/:name

updateShare

ShareInfo
(partial)

ShareInfo

DELETE

<prefix>/shares/:name

deleteShare

None

None

GET

<prefix>/shares/:name/permissions

getSharePermissions

None

PermissionsList

PATCH

<prefix>/shares/:name/permissions

updateSharePermissions

PermissionsDiff

PermissionsList

Endpoint Behavior Notes

Authorization

The createShare endpoint requires that either the user

  1. is a Metastore admin
  2. has CREATE SHARE privilege on the Metastore

The getShare endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Share

The  listShares endpoint returns either:

  1. all Shares (within the current Metastore), when the user is a Metastore admin
  2. all Shares (within the current Metastore) for which the user is the owner

In general, the updateShare endpoint requires either:

  1. the user is the owner of the Share
  2. the user is a Metastore admin and only the owner field is changed

In the case that the Share name is changed, updateShare requires that the user is both the Share owner and a Metastore admin.

For each table that is added through updateShare, the Share owner must also have SELECT privilege on the table. This privilege must be maintained indefinitely for recipients to be able to access the table. Thus, it is highly recommended to use a group as a Share owner.

Table removals through updateShare do not require additional privileges.

The deleteShare endpoint requires that the user is an owner of the Share.

The getSharePermissions endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Share

The updateSharePermissions endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Share

For new recipient grants, the user must also be the owner of the recipients.

Recipient revocations do not require additional privileges.

Recipient CRUD API (Delta Sharing)

Object Models

RecipientInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Recipient relative to parent metastore

authentication_type

string

REQ

IGN

The delta sharing authentication type. Can be "TOKEN" or "DATABRICKS"

comment

string

OPT

OPT

User-supplied free-form text

owner

string

IGN[8]

OPT

Username/groupname of Recipient owner

data_recipient_global_metastore_id

string

OPT

IGN

The global UC metastore id provided by the data recipient.

This field is only present when the authentication type is DATABRICKS.

The identifier is of format <cloud>:<region>:<metastore-uuid>.

ip_access_list

Array[IpAccessList]

OPT

OPT

IP Access List. This field is only applicable for the TOKEN authentication type.

Output-only:

created_at

int64

IGN

IGN

Date of Recipient creation

created_by

string

IGN

IGN

Username of Recipient creator

updated_at

int64

IGN

IGN

Date of last update to Recipient

updated_by

string

IGN

IGN

Username of user who last updated Recipient

tokens

Array[RecipientTokenInfo]

IGN

IGN

Recipient Tokens. This field is only present when the authentication type is TOKEN.

cloud

string

IGN

IGN

Cloud vendor of the recipient's UC Metastore.

This field is only present when the authentication type is DATABRICKS.

region

string

IGN

IGN

Cloud region of the recipient's UC Metastore.

This field is only present when the authentication type is DATABRICKS.

metastore_id

string

IGN

IGN

UUID of the recipient's UC Metastore.

This field is only present when the authentication type is DATABRICKS.

IpAccessList

Field Name

Type

Create

Update

Description

allowed_ip_addresses

Array[string]

OPT

OPT

Allowed IP Addresses in CIDR notation. Limit of 100.

RecipientTokenInfo

Field Name

Type

Create

Update

Description

Output-only:

id

string

IGN

IGN

Unique id of the Recipient Token.

activation_url

string

IGN

IGN

Full activation url to retrieve the access token.

It will be empty if the token is already retrieved.

expiration_time

int64

IGN

IGN

Expiration timestamp of the token in epoch milliseconds.

created_at

int64

IGN

IGN

Date of Recipient Token creation

created_by

string

IGN

IGN

Username of Recipient Token creator

updated_at

int64

IGN

IGN

Date of last update to Recipient Token

updated_by

string

IGN

IGN

Username of user who last updated Recipient Token

ShareToPrivilegeAssignment

Field Name

Type

Create

Update

Description

Output-only:

share_name

string

IGN

IGN

The share name.

privilege_assignments

Array[PrivilegeAssignment]

IGN

IGN

The privileges assigned to the principal.

RotateRecipientToken

Field Name

Type

Create

Update

Description

existing_token_expire_in_seconds

int64

IGN

REQ

This will set the expiration_time of existing token only to a smaller timestamp,

it cannot extend the expiration_time. Use 0 to expire the existing token immediately, negative number will return an error.

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/recipients

createRecipient

RecipientInfo
(partial)

RecipientInfo

GET

<prefix>/recipients

listRecipients

None

Array[RecipientInfo]

GET

<prefix>/recipients/:name

getRecipient

None

RecipientInfo

PATCH

<prefix>/recipients/:name

updateRecipient

RecipientInfo
(partial)

RecipientInfo

DELETE

<prefix>/recipients/:name

deleteRecipient

None

None

GET

<prefix>/recipients/:name/share-permissions

getRecipientSharePermissions

None

Array[ShareToPrivilegeAssignment]

POST

<prefix>/recipients/:name/rotate-token

rotateRecipientToken

RotateRecipientToken

RecipientInfo

Endpoint Behavior Notes

Authorization

The createRecipient endpoint requires that either the user

  1. is a Metastore admin
  2. has CREATE RECIPIENT privilege on the Metastore

The getRecipient endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Recipient

The  listRecipients endpoint returns either:

  1. all Recipients (within the current Metastore), when the user is a Metastore admin
  2. all Recipients (within the current Metastore) for which the user is the owner

In general, the updateRecipient endpoint requires either:

  1. the user is the owner of the Recipient
  2. the user is a Metastore admin and only the owner field is changed

In the case that the Recipient name is changed, updateRecipient requires that the user is both the Recipient owner and a Metastore admin.

The deleteRecipient endpoint requires that the user is an owner of the Recipient.

The getRecipientSharePermissions endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Recipient

The rotateRecipientToken endpoint requires that the user is an owner of the Recipient.

Provider CRUD API (Delta Sharing)

Object Models

ProviderInfo

Field Name

Type

Create

Update

Description

name

string

REQ

OPT

Name of Provider relative to parent metastore

authentication_type

string

REQ

IGN

The delta sharing authentication type. Can be "TOKEN" or "DATABRICKS"

comment

string

OPT

OPT

User-supplied free-form text

owner

string

IGN[9]

OPT

Username/groupname of Povider owner

recipient_profile_str

string

OPT

OPT

Applicable for "TOKEN" authentication type only. This is the string with the profile file given to the recipient. See https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md#profile-file-format

In output mode, the bearer token is redacted.

Output-only:

created_at

int64

IGN

IGN

Date of Provider creation

created_by

string

IGN

IGN

Username of Provider creator

updated_at

int64

IGN

IGN

Date of last update to Provider

updated_by

string

IGN

IGN

Username of user who last updated Provider

recipient_profile

RecipientProfile

IGN

IGN

The recipient profile. This field is only present when the authentication type is TOKEN. See https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md#profile-file-format

cloud

string

IGN

IGN

Cloud vendor of the provider's UC Metastore.

This field is only present when the authentication type is DATABRICKS.

region

string

IGN

IGN

Cloud region of the provider's UC Metastore.

This field is only present when the authentication type is DATABRICKS.

metastore_id

string

IGN

IGN

UUID of the provider's UC Metastore.

This field is only present when the authentication type is DATABRICKS.

RecipientProfile

Field Name

Type

Create

Update

Description

Output-only:

share_credentials_version

int32

IGN

IGN

This field is only present when the authentication type is TOKEN.

The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client.

endpoint

string

IGN

IGN

The url of the sharing server.

ProviderShare

Field Name

Type

Create

Update

Description

Output-only:

name

string

IGN

IGN

The name of the Provider Share.

RPC Endpoints

HTTP Method

URI

Endpoint Name

Input

Output

POST

<prefix>/providers

createProvider

ProviderInfo
(partial)

ProviderInfo

GET

<prefix>/providers

listProviders

None

Array[ProviderInfo]

GET

<prefix>/providers/:name

getProvider

None

ProviderInfo

PATCH

<prefix>/providers/:name

updateProvider

ProviderInfo
(partial)

ProviderInfo

DELETE

<prefix>/providers/:name

deleteProvider

None

None

GET

<prefix>/providers/:name/shares

listProviderShares

None

Array[ProviderShare]

Endpoint Behavior Notes

Authorization

The createProvider endpoint requires that either the user

  1. is a Metastore admin
  2. has CREATE PROVIDER privilege on the Metastore

The getProvider endpoint requires that either the user:

  1. is a Metastore admin
  2. is the owner of the Provider

The  listProviders endpoint returns either:

  1. all Providers (within the current Metastore), when the user is a Metastore admin
  2. all Providers (within the current Metastore) for which the user is the owner

In general, the updateProvider endpoint requires either:

  1. the user is the owner of the Provider
  2. the user is a Metastore admin and only the owner field is changed

In the case that the Provider name is changed, updateProvider requires that the user is both the Provider owner and a Metastore admin.

The deleteProvider endpoint requires that the user is an owner of the Provider.

The listProviderShares endpoint requires that the user is:

  1. is a Metastore admin
  2. is the owner of the Provider

[1] On Create, the new object’s owner field is set to the username of the user performing the operation.

[2] On Create, the new object’s owner field is set to the username of the user performing the operation.

[3] On Create, the new object’s owner field is set to the username of the user performing the operation.

[4] On Create, the new object’s owner field is set to the username of the user performing the operation.

[5] On Create, the new object’s owner field is set to the username of the user performing the operation.

[6] On Create, the new object’s owner field is set to the username of the user performing the operation.

[7] On Create, the new object’s owner field is set to the username of the user performing the operation.

[8] On Create, the new object’s owner field is set to the username of the user performing the operation.

[9] On Create, the new object’s owner field is set to the username of the user performing the operation.