Catalog

View as Markdown

GetGET /api/2.1/unity-catalog/catalogs/{name_arg}ListGET /api/2.1/unity-catalog/catalogsCreatePOST /api/2.1/unity-catalog/catalogsUpdatePATCH /api/2.1/unity-catalog/catalogs/{name_arg}DeleteDELETE /api/2.1/unity-catalog/catalogs/{name_arg}

CatalogInfo object

namestring

Name of catalog.

ownerstring

Username of current owner of catalog.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for managed tables within catalog.

enable_predictive_optimizationstring

Whether predictive optimization should be enabled for this object and objects under it.

catalog_typestring

Values: MANAGED_CATALOG, DELTASHARING_CATALOG, SYSTEM_CATALOG, INTERNAL_CATALOG, FOREIGN_CATALOG, MANAGED_ONLINE_CATALOG

provider_namestring

The name of delta sharing provider.

A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server.

share_namestring

The name of the share under the share provider.

connection_namestring

The name of the connection to an external data source.

metastore_idstring

Unique identifier of parent metastore.

created_atint64

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

created_bystring

Username of catalog creator.

updated_atint64

Time at which this catalog was last modified, in epoch milliseconds.

updated_bystring

Username of user who last modified catalog.

storage_locationstring

Storage Location URL (full path) for managed tables within catalog.

isolation_modestring

Whether the current securable is accessible from all workspaces or a specific set of workspaces.

Values: OPEN, ISOLATED

effective_predictive_optimization_flagobject

Show child attributesHide child attributes

valuestring

Whether predictive optimization should be enabled for this object and objects under it.

inherited_from_typestring

The type of the object from which the flag was inherited. If there was no inheritance, this field is left blank.

inherited_from_namestring

The name of the object from which the flag was inherited. If there was no inheritance, this field is left blank.

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

provisioning_infoobject

Show child attributesHide child attributes

statestring

The provisioning state of the resource.

Values: STATE_UNSPECIFIED, PROVISIONING, ACTIVE, FAILED, DELETING, UPDATING, DEGRADED

full_namestring

The full name of the catalog. Corresponds with the name field.

securable_typestring

Default: CATALOG

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

custom_max_retention_hoursint64Public Preview

Custom maximum retention period in hours for the catalog

managed_encryption_settingsobject

Control CMK encryption for managed catalog data

Show child attributesHide child attributes

customer_managed_key_idstring

the CMK uuid in AWS and GCP, null otherwise.

azure_key_vault_key_idstring

the AKV URL in Azure, null otherwise.

azure_encryption_settingsobject

optional Azure settings - only required if an Azure CMK is used.

Show child attributesHide child attributes

azure_tenant_idstring

azure_cmk_access_connector_idstring

azure_cmk_managed_identity_idstring

propertiesobject

A map of key-value properties attached to the securable.

optionsobject

A map of key-value properties attached to the securable.

View as Markdown

The CatalogInfo object

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "catalog_type": "string",
  "provider_name": "string",
  "share_name": "string",
  "connection_name": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string",
  "isolation_mode": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "browse_only": true,
  "provisioning_info": {
    "state": "string"
  },
  "full_name": "string",
  "securable_type": "string",
  "custom_max_retention_hours": 0,
  "managed_encryption_settings": {
    "customer_managed_key_id": "string",
    "azure_key_vault_key_id": "string",
    "azure_encryption_settings": {}
  },
  "properties": {},
  "options": {}
}

Get GA

GET /api/2.1/unity-catalog/catalogs/{name_arg}

Gets the specified catalog in a metastore. The caller must be a metastore admin, the owner of the catalog, or a user that has the USE_CATALOG privilege set for their account.

API scopes: unity-catalog

Parameters

name_argstringpath

The name of the catalog.

include_browsebooleanquery

Whether to include catalogs in the response for which the principal can only access selective metadata for

Response

Returns the CatalogInfo object.

View as Markdown

Response

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "catalog_type": "string",
  "provider_name": "string",
  "share_name": "string",
  "connection_name": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string",
  "isolation_mode": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "browse_only": true,
  "provisioning_info": {
    "state": "string"
  },
  "full_name": "string",
  "securable_type": "string",
  "custom_max_retention_hours": 0,
  "managed_encryption_settings": {
    "customer_managed_key_id": "string",
    "azure_key_vault_key_id": "string",
    "azure_encryption_settings": {}
  },
  "properties": {},
  "options": {}
}

List GA

GET /api/2.1/unity-catalog/catalogs

Gets an array of catalogs in the metastore. If the caller is the metastore admin, all catalogs will be retrieved. Otherwise, only catalogs owned by the caller (or for which the caller has the USE_CATALOG privilege) will be retrieved. 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

include_browsebooleanquery

Whether to include catalogs in the response for which the principal can only access selective metadata for

max_resultsint32query

Maximum number of catalogs to return.

• when set to 0, the page length is set to a server configured value (recommended);
• 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 a value less than 0, an invalid parameter error is returned;
• If not set, all valid catalogs are returned (not recommended).
• Note: The number of returned catalogs might be less than the specified max_results size, even zero. The only definitive indication that no further catalogs can be fetched is when the next_page_token is unset from the response.

Constraints: <= 1000

page_tokenstringquery

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

include_unboundbooleanquery

Whether to include catalogs not bound to the workspace. Effective only if the user has permission to update the catalog–workspace binding.

Response

Returns a list of CatalogInfo objects.

View as Markdown

Response

{
  "catalogs": [
    {
      "name": "string",
      "owner": "string",
      "comment": "string",
      "storage_root": "string",
      "enable_predictive_optimization": "string",
      "catalog_type": "string",
      "provider_name": "string",
      "share_name": "string",
      "connection_name": "string",
      "metastore_id": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "storage_location": "string",
      "isolation_mode": "string",
      "effective_predictive_optimization_flag": {},
      "browse_only": true,
      "provisioning_info": {},
      "full_name": "string",
      "securable_type": "string",
      "custom_max_retention_hours": 0,
      "managed_encryption_settings": {},
      "properties": {},
      "options": {}
    }
  ],
  "next_page_token": "string"
}

Create GA

POST /api/2.1/unity-catalog/catalogs

Creates a new catalog instance in the parent metastore if the caller is a metastore admin or has the CREATE_CATALOG privilege.

API scopes: unity-catalog

Request body

namestring

Name of catalog.

ownerstring

Username of current owner of catalog.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for managed tables within catalog.

enable_predictive_optimizationstring

Whether predictive optimization should be enabled for this object and objects under it.

catalog_typestring

Values: MANAGED_CATALOG, DELTASHARING_CATALOG, SYSTEM_CATALOG, INTERNAL_CATALOG, FOREIGN_CATALOG, MANAGED_ONLINE_CATALOG

provider_namestring

The name of delta sharing provider.

A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server.

share_namestring

The name of the share under the share provider.

connection_namestring

The name of the connection to an external data source.

metastore_idstring

Unique identifier of parent metastore.

created_atint64

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

created_bystring

Username of catalog creator.

updated_atint64

Time at which this catalog was last modified, in epoch milliseconds.

updated_bystring

Username of user who last modified catalog.

storage_locationstring

Storage Location URL (full path) for managed tables within catalog.

isolation_modestring

Whether the current securable is accessible from all workspaces or a specific set of workspaces.

Values: OPEN, ISOLATED

effective_predictive_optimization_flagobject

Show child attributesHide child attributes

valuestring

Whether predictive optimization should be enabled for this object and objects under it.

inherited_from_typestring

The type of the object from which the flag was inherited. If there was no inheritance, this field is left blank.

inherited_from_namestring

The name of the object from which the flag was inherited. If there was no inheritance, this field is left blank.

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

provisioning_infoobject

Show child attributesHide child attributes

statestring

The provisioning state of the resource.

Values: STATE_UNSPECIFIED, PROVISIONING, ACTIVE, FAILED, DELETING, UPDATING, DEGRADED

full_namestring

The full name of the catalog. Corresponds with the name field.

securable_typestring

Default: CATALOG

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

custom_max_retention_hoursint64Public Preview

Custom maximum retention period in hours for the catalog

managed_encryption_settingsobject

Control CMK encryption for managed catalog data

Show child attributesHide child attributes

customer_managed_key_idstring

the CMK uuid in AWS and GCP, null otherwise.

azure_key_vault_key_idstring

the AKV URL in Azure, null otherwise.

azure_encryption_settingsobject

optional Azure settings - only required if an Azure CMK is used.

Show child attributesHide child attributes

azure_tenant_idstring

azure_cmk_access_connector_idstring

azure_cmk_managed_identity_idstring

propertiesobject

A map of key-value properties attached to the securable.

optionsobject

A map of key-value properties attached to the securable.

Response

Returns the CatalogInfo object.

View as Markdown

Request

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "catalog_type": "string",
  "provider_name": "string",
  "share_name": "string",
  "connection_name": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string",
  "isolation_mode": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "browse_only": true,
  "provisioning_info": {
    "state": "string"
  },
  "full_name": "string",
  "securable_type": "string",
  "custom_max_retention_hours": 0,
  "managed_encryption_settings": {
    "customer_managed_key_id": "string",
    "azure_key_vault_key_id": "string",
    "azure_encryption_settings": {}
  },
  "properties": {},
  "options": {}
}

Response

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "catalog_type": "string",
  "provider_name": "string",
  "share_name": "string",
  "connection_name": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string",
  "isolation_mode": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "browse_only": true,
  "provisioning_info": {
    "state": "string"
  },
  "full_name": "string",
  "securable_type": "string",
  "custom_max_retention_hours": 0,
  "managed_encryption_settings": {
    "customer_managed_key_id": "string",
    "azure_key_vault_key_id": "string",
    "azure_encryption_settings": {}
  },
  "properties": {},
  "options": {}
}

Update GA

PATCH /api/2.1/unity-catalog/catalogs/{name_arg}

Updates the catalog that matches the supplied name. The caller must be either the owner of the catalog, or a metastore admin (when changing the owner field of the catalog).

API scopes: unity-catalog

Parameters

name_argstringpath

The name of the catalog.

Request body

new_namestring

New name for the catalog.

namestring

Name of catalog.

ownerstring

Username of current owner of catalog.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for managed tables within catalog.

enable_predictive_optimizationstring

Whether predictive optimization should be enabled for this object and objects under it.

catalog_typestring

Values: MANAGED_CATALOG, DELTASHARING_CATALOG, SYSTEM_CATALOG, INTERNAL_CATALOG, FOREIGN_CATALOG, MANAGED_ONLINE_CATALOG

provider_namestring

The name of delta sharing provider.

A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server.

share_namestring

The name of the share under the share provider.

connection_namestring

The name of the connection to an external data source.

metastore_idstring

Unique identifier of parent metastore.

created_atint64

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

created_bystring

Username of catalog creator.

updated_atint64

Time at which this catalog was last modified, in epoch milliseconds.

updated_bystring

Username of user who last modified catalog.

storage_locationstring

Storage Location URL (full path) for managed tables within catalog.

isolation_modestring

Whether the current securable is accessible from all workspaces or a specific set of workspaces.

Values: OPEN, ISOLATED

effective_predictive_optimization_flagobject

Show child attributesHide child attributes

valuestring

Whether predictive optimization should be enabled for this object and objects under it.

inherited_from_typestring

The type of the object from which the flag was inherited. If there was no inheritance, this field is left blank.

inherited_from_namestring

The name of the object from which the flag was inherited. If there was no inheritance, this field is left blank.

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

provisioning_infoobject

Show child attributesHide child attributes

statestring

The provisioning state of the resource.

Values: STATE_UNSPECIFIED, PROVISIONING, ACTIVE, FAILED, DELETING, UPDATING, DEGRADED

full_namestring

The full name of the catalog. Corresponds with the name field.

securable_typestring

Default: CATALOG

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

custom_max_retention_hoursint64Public Preview

Custom maximum retention period in hours for the catalog

managed_encryption_settingsobject

Control CMK encryption for managed catalog data

Show child attributesHide child attributes

customer_managed_key_idstring

the CMK uuid in AWS and GCP, null otherwise.

azure_key_vault_key_idstring

the AKV URL in Azure, null otherwise.

azure_encryption_settingsobject

optional Azure settings - only required if an Azure CMK is used.

Show child attributesHide child attributes

azure_tenant_idstring

azure_cmk_access_connector_idstring

azure_cmk_managed_identity_idstring

propertiesobject

A map of key-value properties attached to the securable.

optionsobject

A map of key-value properties attached to the securable.

Response

Returns the CatalogInfo object.

View as Markdown

Request

{
  "new_name": "string",
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "catalog_type": "string",
  "provider_name": "string",
  "share_name": "string",
  "connection_name": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string",
  "isolation_mode": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "browse_only": true,
  "provisioning_info": {
    "state": "string"
  },
  "full_name": "string",
  "securable_type": "string",
  "custom_max_retention_hours": 0,
  "managed_encryption_settings": {
    "customer_managed_key_id": "string",
    "azure_key_vault_key_id": "string",
    "azure_encryption_settings": {}
  },
  "properties": {},
  "options": {}
}

Response

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "catalog_type": "string",
  "provider_name": "string",
  "share_name": "string",
  "connection_name": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string",
  "isolation_mode": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "browse_only": true,
  "provisioning_info": {
    "state": "string"
  },
  "full_name": "string",
  "securable_type": "string",
  "custom_max_retention_hours": 0,
  "managed_encryption_settings": {
    "customer_managed_key_id": "string",
    "azure_key_vault_key_id": "string",
    "azure_encryption_settings": {}
  },
  "properties": {},
  "options": {}
}

Delete GA

DELETE /api/2.1/unity-catalog/catalogs/{name_arg}

Deletes the catalog that matches the supplied name. The caller must be a metastore admin or the owner of the catalog.

API scopes: unity-catalog

Parameters

name_argstringpath

The name of the catalog.

forcebooleanquery

Force deletion even if the catalog is not empty.

View as Markdown

Response

{}