Skip to main content

Metastore

View as Markdown

MetastoreInfo object​

namestring

The user-specified name of the metastore.

storage_rootstring

The storage root URL for metastore

default_data_access_config_idstring

Unique identifier of the metastore's (Default) Data Access Configuration.

storage_root_credential_idstring

UUID of storage credential to access the metastore storage_root.

delta_sharing_scopestring

The scope of Delta Sharing enabled for the metastore.

Values: INTERNAL, INTERNAL_AND_EXTERNAL

delta_sharing_recipient_token_lifetime_in_secondsint64

The lifetime of delta sharing recipient token in seconds.

delta_sharing_organization_namestring

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

ownerstring

The owner of the metastore.

privilege_model_versionstring

Privilege model version of the metastore, of the form major.minor (e.g., 1.0).

regionstring

Cloud region which the metastore serves (e.g., us-west-2, westus).

metastore_idstring

Unique identifier of metastore.

created_atint64

Time at which this metastore was created, in epoch milliseconds.

created_bystring

Username of metastore creator.

updated_atint64

Time at which the metastore was last modified, in epoch milliseconds.

updated_bystring

Username of user who last modified the metastore.

storage_root_credential_namestring

Name of the storage credential to access the metastore storage_root.

cloudstring

Cloud vendor of the metastore home shard (e.g., aws, azure, gcp).

global_metastore_idstring

Globally unique metastore ID across clouds and regions, of the form cloud:region:metastore_id.

external_access_enabledboolean

Whether to allow non-DBR clients to directly access entities under the metastore.

Get GA​

GET /api/2.1/unity-catalog/metastores/{id}

Gets a metastore that matches the supplied ID. The caller must be a metastore admin to retrieve this info.

API scopes: unity-catalog

Parameters​

idstringpath

Unique ID of the metastore.

Response​

Returns the MetastoreInfo object.

List GA​

GET /api/2.1/unity-catalog/metastores

Gets an array of the available metastores (as MetastoreInfo objects). The caller must be an admin to retrieve this info. There is no guarantee of a specific ordering of the elements in the array.

NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters​

max_resultsint32query

Maximum number of metastores to return.

  • when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
  • when set to 0, the page length is set to a server configured value (recommended);
  • when set to a value less than 0, an invalid parameter error is returned;
  • If not set, all the metastores are returned (not recommended).
  • Note: The number of returned metastores might be less than the specified max_results size, even zero. The only definitive indication that no further metastores can be fetched is when the next_page_token is unset from the response.
page_tokenstringquery

Opaque pagination token to go to next page based on previous query.

Response​

Returns a list of MetastoreInfo objects.

Create GA​

POST /api/2.1/unity-catalog/metastores

Creates a new metastore based on a provided name and optional storage root path. By default (if the owner field is not set), the owner of the new metastore is the user calling the createMetastore API. If the owner field is set to the empty string (""), the ownership is assigned to the System User instead.

API scopes: unity-catalog

Request body​

namestring

The user-specified name of the metastore.

storage_rootstring

The storage root URL for metastore

default_data_access_config_idstring

Unique identifier of the metastore's (Default) Data Access Configuration.

storage_root_credential_idstring

UUID of storage credential to access the metastore storage_root.

delta_sharing_scopestring

The scope of Delta Sharing enabled for the metastore.

Values: INTERNAL, INTERNAL_AND_EXTERNAL

delta_sharing_recipient_token_lifetime_in_secondsint64

The lifetime of delta sharing recipient token in seconds.

delta_sharing_organization_namestring

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

ownerstring

The owner of the metastore.

privilege_model_versionstring

Privilege model version of the metastore, of the form major.minor (e.g., 1.0).

regionstring

Cloud region which the metastore serves (e.g., us-west-2, westus).

metastore_idstring

Unique identifier of metastore.

created_atint64

Time at which this metastore was created, in epoch milliseconds.

created_bystring

Username of metastore creator.

updated_atint64

Time at which the metastore was last modified, in epoch milliseconds.

updated_bystring

Username of user who last modified the metastore.

storage_root_credential_namestring

Name of the storage credential to access the metastore storage_root.

cloudstring

Cloud vendor of the metastore home shard (e.g., aws, azure, gcp).

global_metastore_idstring

Globally unique metastore ID across clouds and regions, of the form cloud:region:metastore_id.

external_access_enabledboolean

Whether to allow non-DBR clients to directly access entities under the metastore.

Response​

Returns the MetastoreInfo object.

Update GA​

PATCH /api/2.1/unity-catalog/metastores/{id}

Updates information for a specific metastore. The caller must be a metastore admin. If the owner field is set to the empty string (""), the ownership is updated to the System User.

API scopes: unity-catalog

Parameters​

idstringpath

Unique ID of the metastore.

Request body​

new_namestring

New name for the metastore.

namestring

The user-specified name of the metastore.

storage_rootstring

The storage root URL for metastore

default_data_access_config_idstring

Unique identifier of the metastore's (Default) Data Access Configuration.

storage_root_credential_idstring

UUID of storage credential to access the metastore storage_root.

delta_sharing_scopestring

The scope of Delta Sharing enabled for the metastore.

Values: INTERNAL, INTERNAL_AND_EXTERNAL

delta_sharing_recipient_token_lifetime_in_secondsint64

The lifetime of delta sharing recipient token in seconds.

delta_sharing_organization_namestring

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

ownerstring

The owner of the metastore.

privilege_model_versionstring

Privilege model version of the metastore, of the form major.minor (e.g., 1.0).

regionstring

Cloud region which the metastore serves (e.g., us-west-2, westus).

metastore_idstring

Unique identifier of metastore.

created_atint64

Time at which this metastore was created, in epoch milliseconds.

created_bystring

Username of metastore creator.

updated_atint64

Time at which the metastore was last modified, in epoch milliseconds.

updated_bystring

Username of user who last modified the metastore.

storage_root_credential_namestring

Name of the storage credential to access the metastore storage_root.

cloudstring

Cloud vendor of the metastore home shard (e.g., aws, azure, gcp).

global_metastore_idstring

Globally unique metastore ID across clouds and regions, of the form cloud:region:metastore_id.

external_access_enabledboolean

Whether to allow non-DBR clients to directly access entities under the metastore.

Response​

Returns the MetastoreInfo object.

Delete GA​

DELETE /api/2.1/unity-catalog/metastores/{id}

Deletes a metastore. The caller must be a metastore admin.

API scopes: unity-catalog

Parameters​

idstringpath

Unique ID of the metastore.

forcebooleanquery

Force deletion even if the metastore is not empty. Default is false.