Unity Catalog API Specification

Jun 10, 2022

Table of Contents
Document History

Table of Contents

Purpose and Scope

Terminology
User Types
Metastore Admins
Account Admins
Client Types

API Conventions

API Usage Notes

Common Data Models

Properties

Public APIs
Metastore CRUD API
Object Models
RPC Endpoints
Endpoint Behavior Notes
Authorization
Metastore Summary API
Object Model
RPC Endpoints
Metastore Assignment API
Object Models
RPC Endpoints
Inputs
Endpoint Behavior Notes
Authorization
 Page 2 of 38

Storage Credential CRUD API

Object Models
RPC Endpoints
Endpoint Behavior Notes
Authorization
External Location CRUD API
Object Models
RPC Endpoints
Endpoint Behavior Notes
Authorization
Catalog CRUD API
Object Models
RPC Endpoints
Endpoint Behavior Notes
Authorization
Schema CRUD API
Object Models
RPC Endpoints
Inputs
Endpoint Behavior Notes
Authorization
Staging Table API
Object Models
RPC Endpoints
Endpoint Behavior Notes
Authorization
Table CRUD API
Object Model
RPC Endpoints
Inputs
Endpoint Behavior Notes
Authorization
ListTableSummaries API
Object Models
RPC Endpoints
Endpoint Behavior Notes
Authorization
 Page 3 of 38

Permissions API
Terminology and Permissions Management Model
SQL Object Privileges
Object Models
Changing Ownership
RPC Endpoints
Inputs
Authorization, Error Responses
User-Info API
Object Models
RPC Endpoints
Inputs
Temporary Credential API
Table Operations
Path Operations
Object Models
RPC Endpoints
 Page 4 of 38

Purpose and Scope

This document gives a compact specification of the Unity Catalog (UC) API, focusing on the
messages and endpoints constituting the UC’s Public API.

The following areas are not covered by this document:

● Delta Sharing APIs
● Databricks-internal APIs (e.g., related to Data Lineage or Information Schema)
● Enumerated error codes and descriptions that may be returned by each API
endpoint

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. The Metastore Admins for a given
Metastore are users who are either:
● an Account Admin
● the configured owner of the Metastore in question

Note that a Metastore Admin may or may not be a Workspace Admin for a given workspace
(i.e., being a Workspace Admin does not automatically make the user a Metastore Admin).

Account Admins
An Account Admin is an account-level user with the “Account Owner” role configured in the
Accounts Console. Creating and updating a Metastore can only be done by an Account
Admin. An Account Admin can specify other users to be Metastore Admins by changing the
Metastore’s owner (using updateMetastore endpoint).

Client Types
The Unity Catalog’s API server is accessed by three types of clients:

● PE clusters: clients emanating from ‘trusted’ clusters that perform

 Page 5 of 38

Permissions-Enforcing in the execution engine by filtering data there. These are

clusters with Security Mode = “User Isolation” and thus support SQL only. Their
clients authenticate with internally-generated tokens that include the
unity_catalog:permission_enforcing scope for this purpose. The
PE-restricted API endpoints return results without server-side filtering based on
the permissions of the client user, as the DBR client is trusted to perform such
filtering as necessary.

● NoPE clusters: clients emanating from DBR clusters that support UC and are
Non-Permissions-Enforcing. Currently, the only DBR clusters of this type are those
with Security Mode = “Single User”). These clients authenticate with an
internally-generated token that contains a unity_catalog:cluster scope
(though not the unity_catalog:permission_enforcing scope). For these
clients, the Unity Catalog’s API service enforces access control requirements of the
Unity Catalog Data Governance Model filter data and sends results filtered by the
client user’s permissions.

● External clients: all other clients that are not PE clusters or NoPE clusters. These
clients authenticate with ‘external’ tokens (e.g., PAT tokens obtained from a
Workspace) rather than tokens generated internally for DBR clusters. This includes
client’s using the databricks-cli’s unity-catalog commands to access the UC API.
As with NoPE cluster clients, the UC API endpoints available to these clients also
enforces access control requirements on the server side.

API Conventions
● To simplify management of API message types, the *Info messages are used for
both input (to create*, update* and delete* endpoints) and output (from
create*, get*, list* and update* endpoints). The fields are marked with
REQ/OPT/IGN labels to specify whether they are REQuired, OPTional or IGNored for
each operation (organized by table column in the specification).

● All name fields are UTF-8 strings, initially created by users and visible to users
thereafter. These object names are supplied by users in SQL commands (e.g.,
“CREATE TABLE something ...” or via direct access to the UC API.

Names supplied by users are converted to lower-case by DBR clients (before they
are sent to the UC API) . Also, input names (for all object types except Table Column
Names) are converted to lower-case by the UC server, to handle the case that UC
objects are created via directly accessing the UC API. With this conversion to
 Page 6 of 38

lower-case names, the name handling is effectively case-insensitive. I.e., if a user

creates a table with relative name “FooBar”, it would conflict with an existing table
named “foobar”.

SQL objects are referenced by their full name in the RESTful API URIs, and since
these names are UTF-8 they must be URL-encoded. For example, the request URI
for a table with full name “SomeCÄt.SømeSchëma.テーブル” will be:
/api/2.0/unity-catalog/tables/SomeC%C3%84t.S%C3%B8meSch%C3%ABma.%E3%83%86%E3%83
%BC%E3%83%96%E3%83%AB

● All principals (users and groups) are referenced by their user/group name strings,
not by the User IDs (int64s) used internally by Databricks control plane services.
This means that in the UC API, users are referenced by their email address (e.g.,
“[email protected]”) while groups are referenced by their group names
(e.g., “account users”).

● Timestamps like created_at fields are int64’s (time in epoch milliseconds).

● All storage_root, storage_location and (storage) url fields contain a path

with scheme prefix, e.g.
“abfss://[email protected]/my/path”,
“s3://some-bucket-name/my/path”

● API endpoints listed in red text are not yet implemented.

API Usage Notes

● All operations on Catalogs, Schemas and Tables are performed within the scope of
the Metastore currently assigned to the client user’s workspace (this workspace is
determined from the user’s API authentication token). I.e., currently a user cannot
create a Schema in a Catalog residing in a Metastore that is different from the
Metastore currently assigned to the user’s workspace.

● There is no list of child objects within the *Info structures (e.g., SchemaInfo does
not include a field containing the list of tables within the schema). Getting a list of
child objects requires performing a list* operation on the child object type with
the query arguments specifying the parent identifier (e.g., GET
<prefix>/tables?schema_name=<some_parent_schema_name>)

● The details of error responses are to be specified, but the general form of error the
response body is:
 Page 7 of 38

{
"error_code": "<error_code>",
"message": "<brief user-readable description"
}
The specific error_code values used by each endpoint will be detailed later.

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 NoPE and External clients; that is, they are
not limited to PE 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.

The URI prefix for these endpoints is:

<prefix> = /api/2.0/unity-catalog

Metastore CRUD API

Object Models
DeltaSharingScope
The supported values of the delta_sharing_scope field (within a MetastoreInfo) are
the following strings:
● "UNKNOWN"
Not specified.

● "INTERNAL"
 Page 8 of 38

Internal Delta Sharing enabled on metastore.This applies to Databricks-managed

authentication where both provider and recipient are under the same account.

● "EXTERNAL"
Internal and External Delta Sharing enabled on metastore. This allows all flavors of
Delta Sharing.

MetastoreInfo:

Field Name Type Creat Updat Description

e e

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 string (uuid) IGN OPT Unique identifier of default

[DEPRECATED] 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 IGN1 OPT Username/groupname of Metastore owner

data_sharing_enabled bool IGN OPT Whether delta sharing is enabled for this
Metastore (default: false)

delta_sharing_scope String IGN OPT Delta Sharing Scope.

(DeltaSharingSc
ope)

delta_sharing_recipient_token int32 IGN OPT The lifetime of delta sharing recipient token in
_lifetime_in_seconds seconds (no default; must be specified when
data_sharing_enabled is set to true).

delta_sharing_organization_na string IGN OPT The organization name of a Delta Sharing entity.
me The name will be used in
Databricks-to-Databricks Delta Sharing as the
official name.

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

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 URI Endpoint Name Input Output
Method

POST <prefix>/metastores createMetastore MetastoreInfo MetastoreInfo

(partial)

GET <prefix>/metastores listMetastores None Array[MetastoreInfo]

GET <prefix>/metastores/:id getMetastore None MetastoreInfo

PATCH <prefix>/metastores/:id updateMetastore MetastoreInfo MetastoreInfo

(partial)

DELETE <prefix>/metastores/:id deleteMetastore DeleteMetastoreOpts None

 Page 10 of 38

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

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 string (uuid) Unique identifier of the DAC for accessing table
[DEPRECATED] 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”
 Page 11 of 38

RPC Endpoints
HTTP Method URI Endpoint Name Output

GET <prefix>/metastore_summary getMetastoreSummary MetastoreSummaryInfo

Metastore Assignment API

Object Models
MetastoreAssignment:

Field Name Type Create Update Delet Description

e

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 URI Endpoint Name Input Output
Method

PUT <prefix>/workspaces/ createMetastoreAssignment MetastoreAssignment None

:workspace_id/metastore

PATCH <prefix>/workspaces/ updateMetastoreAssignment MetastoreAssignment None

:workspace_id/metastore

DELETE <prefix>/workspaces/ deleteMetastoreAssignment MetastoreAssignment None

:workspace_id/metastore

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

Endpoint Behavior Notes

● createMetastoreAssignment
If an assignment on the same workspace_id already exists, it will be overwritten by
the new metastore_id and default_catalog_name.
 Page 12 of 38

● updateMetastoreAssignment
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.

● There are no UC API endpoints for reading or listing Metastore Assignments (per
workspace) currently.

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 Creat Update Description

e

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 Creat Update Description

e
 Page 13 of 38

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 Updat Description

e

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 Updat Description

e

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 IGN2 OPT Username/groupname of Storage

Credential owner

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

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 URI Endpoint Name Input Output
Method

POST <prefix>/storage-credentials createStorage StorageCredentialInfo StorageCredential

Credential (partial) Info

GET <prefix>/storage-credentials listStorage None Array[StorageCred

Credentials entialInfo]

GET <prefix>/storage-credentials getStorage None StorageCredential

/:name Credential Info

PATCH <prefix>/storage-credentials updateStorage StorageCredentialInfo StorageCredential

/:name Credential (partial) Info

DELETE <prefix>/storage-credentials deleteStorage DeleteStorageCredenti None

/:name Credential alOpts
 Page 15 of 38

Endpoint Behavior Notes

Authorization

The createStorageCredential endpoint requires that the user is a Metastore admin.

The getStorageCredential endpoint requires that either the user:

1. is a Metastore 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), when the user is a Metastore
admin
2. all Storage Credentials for which the user is the owner or the user has some
privilege

The updateStorageCredential endpoint requires either:

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

The deleteStorageCredntial endpoint requires that the user is an owner of the Storage
Credential.

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

 Page 16 of 38

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 Updat Description

e

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 IGN3 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

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

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 string (uuid) IGN IGN Unique identifier of the External Location
[DEPRECATED]

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 URI Endpoint Name Input Output
Method

POST <prefix>/external-locations createExternal ExternalLocation ExternalLocationInfo

Location Info (partial)

GET <prefix>/external-locations listExternal None Array[ExternalLocation

Locations Info]

GET <prefix>/external-locations getExternal None ExternalLocationInfo

/:name Location

PATCH <prefix>/external-locations updateExternal ExternalLocation ExternalLocationInfo

/:name Location Info (partial)

DELETE <prefix>/external-locations deleteExternal DeleteExternal None

/:name Location LocationOpts

GET <prefix>/files listFiles ListFilesReq ListFilesResp

 Page 18 of 38

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,
● The External Location’s url cannot overlap with (be a child of, a parent of, or the
same as) the url of another External Location
● The External Location’s url cannot be within (a child of or the same as) the url of
an external Table

Authorization

The createExternalLocation endpoint requires that the user is a Metastore admin.

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
 Page 19 of 38

Field Name Type Create Updat Description

e

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 IGN4 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 CatalogInfo

(partial)

GET <prefix>/catalogs listCatalogs None Array[CatalogInfo]

GET <prefix>/catalogs/:name getCatalog None CatalogInfo

PATCH <prefix>/catalogs/:name updateCatalog CatalogInfo CatalogInfo

(partial)

DELETE <prefix>/catalogs/:name deleteCatalog None None

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

Endpoint Behavior Notes

Authorization

The createCatalog endpoint requires that the user is a Metastore Admin.

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 Creat Update Description

e

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

 Page 21 of 38

owner string IGN5 OPT Username/groupname of Schema owner

properties Map[string, OPT OPT Extensible Schema properties

string]

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 URI Endpoint Name Input Output
Method

POST <prefix>/schemas createSchema SchemaInfo SchemaInfo

(partial)

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 SchemaInfo

(partial)

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

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

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.
 Page 23 of 38

Staging Table API

These API endpoints are used for CTAS (Create Table As Select) or delta table creation
where Spark needs to write data first then commit metadata to Unity Catalog. The Staging
Table API endpoints are intended for use by DBR clusters only.

Object Models
StagingTableInfo:

Field Name Type Creat Description

e

name string REQ Name of table

catalog_name string REQ Name of parent Catalog

schema_name string REQ Name of parent Schema relative to its parent

Catalog

Output-only:

id string (uuid) IGN Unique identifier for staging table which would be
promoted to be actual table id

staging_location string IGN Storage root URL generated for the staging table

RPC Endpoints
HTTP URI Endpoint Name Input Output
Method

POST <prefix>/stagingF-table createStagingTable StagingTableInfo StagingTableInfo

s (partial)

Endpoint Behavior Notes

Authorization

The createStagingTable endpoint requires that the user have both

1. the USAGE privilege on the parent Catalog
2. the USAGE and CREATE privileges on the parent Schema
 Page 24 of 38

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 OPT SQL text defining the view (for
View 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 IGN6 OPT Username/groupname of Table owner

properties Map[string,string] OPT OPT Extensible Table properties

Output-only:

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

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 string (uuid) IGN IGN Unique identifier of

[DEPRECATED] 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:
● "MANAGED"
● "EXTERNAL"
● "VIEW"

Column Type Name

The supported values of the type_name field (within a ColumnInfo) are the following
strings:
● "BOOLEAN"
● "BYTE" (SQL alias: "TINYINT")
● "SHORT" (SQL alias: "SMALLINT")
● "INT" (SQL alias: "INTEGER")
● "LONG" (SQL alias: "BIGINT")
● "FLOAT" (SQL alias: "REAL")
● "DOUBLE"
● "DATE"
● "TIMESTAMP"
● "STRING"
● "BINARY"
● "DECIMAL" (SQL aliases: "DEC", "NUMERIC")
 Page 26 of 38

● "INTERVAL"
● "ARRAY"
● "STRUCT"
● "MAP"
● "CHAR"
● "NULL"

Data Source Format

External tables are supported in multiple data source formats. The string constants
identifying these formats are:
● "DELTA"
● "CSV"
● "JSON"
● "AVRO"
● "PARQUET"
● "ORC"
● "TEXT"
● "UNITY_CATALOG" (a Table within the Unity Catalog’s Information Schema)
● "DELTASHARING" (a Table shared through the Delta Sharing protocol)

ColumnInfo

Field Name Type Create Updat Description

e

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

 Page 27 of 38

RPC Endpoints
HTTP URI Endpoint Name Input Output
Method

POST <prefix>/tables createTable TableInfo TableInfo

(partial)

GET <prefix>/tables[?<q_args>] listTables q_args TableList

GET <prefix>/tables/:full_name getTable None TableInfo

PATCH <prefix>/tables/:full_name updateTable TableInfo TableInfo

(partial)

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 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
 Page 28 of 38

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 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, 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 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/OP Description

T
 Page 29 of 38

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 URI Endpoint Name Input Output
Method

POST <prefix>/table-summaries listTableSummaries TableSummariesReq TableSummaries

Resp

Endpoint Behavior Notes

Authorization

The listTables endpoint returns either:

 Page 30 of 38

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:

● Principal: a username (email address) or group name (including the special group
“account users”, to which all users belong)

● Securable: an SQL object (Catalog, Schema, Table) or other object managed by

Unity Catalog (e.g., Shares)

● Privileges: a collection of specific abilities (on a securable)

● Permissions: a mapping of principals (users/groups) to privileges

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

securable (object).

SQL Object Privileges

The Unity Catalog data governance model is an allowlist (i.e., there are no privileges
inherited from Catalog to Schema to Table, in contrast to the Hive metastore permissions
model and the inheritance model used with objects managed by the Permissions API), so
there are no explicit DENY actions.
 Page 31 of 38

The supported privilege values on Metastore SQL Objects (Catalogs, Schemas, Tables) are
the following strings:
● "USAGE"
● "SELECT"
● "MODIFY"
● "CREATE"
External Locations and Storage Credentials support the following privileges:
● "READ_FILES"
● "WRITE_FILES"
● "CREATE_TABLE"

Note there is no "ALL" privilege. It is the responsibility of the API client to translate the set
of all privileges to/from the "ALL" alias.

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": "[email protected]",
"privileges": ["SELECT"]
},`
 Page 32 of 38

{
"principal": "eng-data-security",
"privileges": ["SELECT","MODIFY","CREATE"]
},
{
"principal": "users",
"privileges": ["USAGE"]
}
]
}

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": "[email protected]",
"add": ["SELECT"],
"remove": ["MODIFY"]
},
 Page 33 of 38

{
"principal": "eng-data-security",
"remove": ["CREATE"]
},
{
"principal": "users",
"add": ["USAGE"]
}
]
}

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

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

 Page 34 of 38

HTTP URI Endpoint Name Input Output

Method

GET <prefix>/permissions/<sec_type>/ getPermissions q_args PermissionsList

<sec_full_name>[?q_args]

PATCH <prefix>/permissions/<sec_type>/ updatePermissions PermissionsDiff PermissionsList

<sec_full_name>

PUT <prefix>/permissions/<sec_type>/ replacePermissions PermissionsList None

<sec_full_name>

Examples:
GET /api/2.0/unity-catalog/permissions/catalog/some_cat
PUT /api/2.0/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:
● getPermissions:
○ If the client user is the owner of the securable or a Metastore admin:
■ If a principal input is provided, only return the permissions of that
principal on the securable.
■ If no principal input is provided, all configured permissions on the
securable are returned if no principal input is provided.
○ If the client user is not the owner of the securable and not a Metastore admin
and the principal supplied matches the client user:
■ The privileges granted to that principal are returned.
○ Otherwise, the endpoint will return a 403 - Forbidden with the body:
{
"error_code": "UNAUTHORIZED",
"message": "Only admin users or the owner of the securable can
read other users' permissions."
 Page 35 of 38

● updatePermissions, replacePermissions:
○ If the client user is not the owner of the securable or a Metastore admin, the
endpoint will return a 403 with the error body:
{
"error_code": "UNAUTHORIZED",
"message": "Users can only grant or revoke schema and table
permissions."
}

○ If the Permissions / PermissionsChanges input is invalid (e.g., the

PermissionsChanges input attempts to "add" the "SELECT" permission to a
schema), the endpoint will return a 400 with an appropriate error body.

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 URI Endpoint Name Input Output
Method

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

GET <prefix>/user-info/my-groups getMyGroups GetMyGroupsReq GetMyGroupsResp

 Page 36 of 38

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

Temporary Credential API

Table Operations
The supported values for the operation fields of the
GenerateTemporaryTableCredentialReq message are:
● "READ" – for read-only access to Table data in cloud storage
● "READ_WRITE" – for read and write access to Table data in cloud storage

Path Operations
The supported values for the operation fields of the
GenerateTemporaryPathCredentialReq message are:
● "PATH_READ" – for read-only access to data in cloud storage path
● "PATH_READ_WRITE" – for read and write access to data in cloud storage path
● "PATH_CREATE_TABLE" – for table creation with cloud storage path

Object Models
AwsCredentials:

Field Name Type Description

access_key_id string The access key ID that identifies the temporary credentials

secret_access_key string The secret access key that can be used to sign AWS API requests

session_token string The token that users must pass to AWS API to use the temporary
credentials

AzureUserDelegationSAS:

Field Name Type Description

sas_token string The signed URI (SAS Token) used to access blob services for a
given path
 Page 37 of 38

GcpOauthToken:

Field Name Type Description

oauth_token string GCP temporary credentials for API authentication (ref)

TemporaryCredentials:

Field Name Type Description

expiration_time int64 Server time when the credential will expire, in

epoch milliseconds

Credentials – one of:

aws_temp_credentials AwsCredentials Temporary credentials for AWS

azure_user_delegation_sas AzureUserDelegationSAS Azure signed URI (SAS Token)

gcp_oauth_token GcpOauthToken GCP OAuth token

GenerateTemporaryTableCredentialReq:

Field Name Type Description

table_id string (uuid) Unique identifier of the Table

operation string One of the Table Operation values above

GenerateTemporaryPathCredentialReq:

Field Name Type Description

url string (url) URL of path in cloud storage

operation string One of the Path Operation values above

credential_id string (uuid) Unique ID of the Storage Credential to use to obtain the
temporary credential

RPC Endpoints
HTTP URI Endpoint Name Input Output
Method

POST <prefix>/temporary-table- generateTemporary GenerateTemporary TemporaryCredentials

credentials TableCredential TableCredentialReq
 Page 38 of 38

POST <prefix>/temporary-path- generateTemporary GenerateTemporary TemporaryCredentials

credential PathCredential PathCredentialReq