Catalog
A catalog is the first layer of Unity Catalog's three-level namespace and groups the schemas, tables, volumes, and other data assets under it. Catalogs created through this API are standard catalogs, Delta Sharing catalogs created from a share, or foreign catalogs that mirror a database behind a connection to an external data source.
CatalogInfo object
A catalog is the first layer of Unity Catalog's three-level namespace and groups the schemas, tables, volumes, and other data assets under it. Catalogs created through this API are standard catalogs, Delta Sharing catalogs created from a share, or foreign catalogs that mirror a database behind a connection to an external data source.
- namestring
The name of the catalog is stored in lowercase, can be at most 255 characters long, and cannot contain periods, spaces, forward slashes, or control characters.
- ownerstring
Username of current owner of catalog.
- commentstring
User-provided free-form text description.
- storage_rootstring
Managed tables and volumes in the catalog are stored under this storage root URL. The path must be inside an external location on which the caller has the CREATE MANAGED STORAGE privilege. If omitted, managed data is stored under the metastore's root storage location, which must then be configured. Delta Sharing catalogs cannot have a storage root.
- enable_predictive_optimizationstring
Whether predictive optimization is enabled for this catalog and the objects under it. Valid values are ENABLE, DISABLE, and INHERIT, where INHERIT applies the account-level setting. Standard catalogs start as INHERIT and other catalog types as DISABLE. It cannot be set when creating a catalog; use the update method instead.
- catalog_typestring
The server sets the catalog type from the create request. Catalogs created through this API are MANAGED_CATALOG (standard catalogs), DELTASHARING_CATALOG when created from a share with provider_name and share_name, or FOREIGN_CATALOG when created from a connection with connection_name. The remaining types are provisioned by Databricks.
MANAGED_CATALOGDELTASHARING_CATALOGSYSTEM_CATALOGINTERNAL_CATALOGFOREIGN_CATALOGMANAGED_ONLINE_CATALOG
- provider_namestring
The Delta Sharing provider that owns the share must be named here, together with share_name, to create a Delta Sharing catalog that exposes the data of the share on a remote sharing server. The provider cannot be changed after creation.
- connection_namestring
Naming a connection to an external data source creates a foreign catalog that mirrors a database in that source, which requires ownership of or the CREATE FOREIGN CATALOG privilege on the connection. Connection-specific settings, such as the database to mirror, go in options. The connection cannot be changed after creation.
- 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
The server derives this full storage location URL for managed tables and volumes within the catalog from storage_root and the catalog ID.
- isolation_modestring
Whether the catalog is accessible from all workspaces attached to the metastore (OPEN) or only from the workspaces bound to it (ISOLATED). It cannot be set when creating a catalog; change it with the update method and manage the bound workspaces with the workspace bindings API. See Workspace-catalog binding.
OPENISOLATED
- effective_predictive_optimization_flagobject
Indicates the predictive optimization setting that is in effect for the catalog once inherited values are resolved.
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
Indicates the provisioning status of the catalog. It is present only for catalogs that are provisioned asynchronously.
Show child attributesHide child attributes
- statestring
The provisioning state of the resource.
PROVISIONINGACTIVEFAILEDDELETINGUPDATINGDEGRADED
- full_namestring
The full name of the catalog. Corresponds with the name field.
- securable_typestring
The securable type is always CATALOG for a catalog.
Show 24 possible values
CATALOGSCHEMATABLESTORAGE_CREDENTIALEXTERNAL_LOCATIONFUNCTIONSHAREPROVIDERRECIPIENTCLEAN_ROOMMETASTOREPIPELINEVOLUMECONNECTIONCREDENTIALEXTERNAL_METADATASTAGING_TABLEMODELMODEL_SERVICEMCP_SERVICEMODEL_PROVIDER_SERVICEAGENT_SERVICEBetaSKILLBetaFEATURE
- custom_max_retention_hoursint64Public Preview
Dropped objects in the catalog remain recoverable for this number of hours before they are permanently purged. The value applies to standard catalogs only, must be 0 or within the range allowed for the metastore, and is inherited by schemas and tables that do not set their own value.
- managed_encryption_settingsobject
Customer-managed key (CMK) settings control the encryption at rest of the catalog's managed 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.
Get a catalog GA
GET
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_argstringRequiredpath
The name of the catalog.
- include_browsebooleanquery
Whether to return the catalog when the principal can only access selective metadata for it through the BROWSE privilege. The response then has browse_only set to true.
Response
Returns the CatalogInfo object.
List catalogs GA
GET
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 for which the principal can only access selective metadata through the BROWSE privilege. Such catalogs are returned with browse_only set to true.
- max_resultsint32<= 1000query
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.
- 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.
Create a catalog GA
POST
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
The name of the catalog is stored in lowercase, can be at most 255 characters long, and cannot contain periods, spaces, forward slashes, or control characters.
- ownerstring
Username of current owner of catalog.
- commentstring
User-provided free-form text description.
- storage_rootstring
Managed tables and volumes in the catalog are stored under this storage root URL. The path must be inside an external location on which the caller has the CREATE MANAGED STORAGE privilege. If omitted, managed data is stored under the metastore's root storage location, which must then be configured. Delta Sharing catalogs cannot have a storage root.
- enable_predictive_optimizationstring
Whether predictive optimization is enabled for this catalog and the objects under it. Valid values are ENABLE, DISABLE, and INHERIT, where INHERIT applies the account-level setting. Standard catalogs start as INHERIT and other catalog types as DISABLE. It cannot be set when creating a catalog; use the update method instead.
- catalog_typestring
The server sets the catalog type from the create request. Catalogs created through this API are MANAGED_CATALOG (standard catalogs), DELTASHARING_CATALOG when created from a share with provider_name and share_name, or FOREIGN_CATALOG when created from a connection with connection_name. The remaining types are provisioned by Databricks.
MANAGED_CATALOGDELTASHARING_CATALOGSYSTEM_CATALOGINTERNAL_CATALOGFOREIGN_CATALOGMANAGED_ONLINE_CATALOG
- provider_namestring
The Delta Sharing provider that owns the share must be named here, together with share_name, to create a Delta Sharing catalog that exposes the data of the share on a remote sharing server. The provider cannot be changed after creation.
- connection_namestring
Naming a connection to an external data source creates a foreign catalog that mirrors a database in that source, which requires ownership of or the CREATE FOREIGN CATALOG privilege on the connection. Connection-specific settings, such as the database to mirror, go in options. The connection cannot be changed after creation.
- 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
The server derives this full storage location URL for managed tables and volumes within the catalog from storage_root and the catalog ID.
- isolation_modestring
Whether the catalog is accessible from all workspaces attached to the metastore (OPEN) or only from the workspaces bound to it (ISOLATED). It cannot be set when creating a catalog; change it with the update method and manage the bound workspaces with the workspace bindings API. See Workspace-catalog binding.
OPENISOLATED
- effective_predictive_optimization_flagobject
Indicates the predictive optimization setting that is in effect for the catalog once inherited values are resolved.
Show child attributesHide child attributes
- valuestringRequired
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
Indicates the provisioning status of the catalog. It is present only for catalogs that are provisioned asynchronously.
Show child attributesHide child attributes
- statestring
The provisioning state of the resource.
PROVISIONINGACTIVEFAILEDDELETINGUPDATINGDEGRADED
- full_namestring
The full name of the catalog. Corresponds with the name field.
- securable_typestring
The securable type is always CATALOG for a catalog.
Show 24 possible values
CATALOGSCHEMATABLESTORAGE_CREDENTIALEXTERNAL_LOCATIONFUNCTIONSHAREPROVIDERRECIPIENTCLEAN_ROOMMETASTOREPIPELINEVOLUMECONNECTIONCREDENTIALEXTERNAL_METADATASTAGING_TABLEMODELMODEL_SERVICEMCP_SERVICEMODEL_PROVIDER_SERVICEAGENT_SERVICEBetaSKILLBetaFEATURE
- custom_max_retention_hoursint64Public Preview
Dropped objects in the catalog remain recoverable for this number of hours before they are permanently purged. The value applies to standard catalogs only, must be 0 or within the range allowed for the metastore, and is inherited by schemas and tables that do not set their own value.
- managed_encryption_settingsobject
Customer-managed key (CMK) settings control the encryption at rest of the catalog's managed 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_idstringRequired
- azure_cmk_access_connector_idstring
- azure_cmk_managed_identity_idstring
- propertiesobjectRequired
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.
Update a catalog GA
PATCH
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_argstringRequiredpath
The name of the catalog.
Request body
- new_namestring
New name for the catalog.
- namestring
The name of the catalog is stored in lowercase, can be at most 255 characters long, and cannot contain periods, spaces, forward slashes, or control characters.
- ownerstring
Username of current owner of catalog.
- commentstring
User-provided free-form text description.
- storage_rootstring
Managed tables and volumes in the catalog are stored under this storage root URL. The path must be inside an external location on which the caller has the CREATE MANAGED STORAGE privilege. If omitted, managed data is stored under the metastore's root storage location, which must then be configured. Delta Sharing catalogs cannot have a storage root.
- enable_predictive_optimizationstring
Whether predictive optimization is enabled for this catalog and the objects under it. Valid values are ENABLE, DISABLE, and INHERIT, where INHERIT applies the account-level setting. Standard catalogs start as INHERIT and other catalog types as DISABLE. It cannot be set when creating a catalog; use the update method instead.
- catalog_typestring
The server sets the catalog type from the create request. Catalogs created through this API are MANAGED_CATALOG (standard catalogs), DELTASHARING_CATALOG when created from a share with provider_name and share_name, or FOREIGN_CATALOG when created from a connection with connection_name. The remaining types are provisioned by Databricks.
MANAGED_CATALOGDELTASHARING_CATALOGSYSTEM_CATALOGINTERNAL_CATALOGFOREIGN_CATALOGMANAGED_ONLINE_CATALOG
- provider_namestring
The Delta Sharing provider that owns the share must be named here, together with share_name, to create a Delta Sharing catalog that exposes the data of the share on a remote sharing server. The provider cannot be changed after creation.
- connection_namestring
Naming a connection to an external data source creates a foreign catalog that mirrors a database in that source, which requires ownership of or the CREATE FOREIGN CATALOG privilege on the connection. Connection-specific settings, such as the database to mirror, go in options. The connection cannot be changed after creation.
- 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
The server derives this full storage location URL for managed tables and volumes within the catalog from storage_root and the catalog ID.
- isolation_modestring
Whether the catalog is accessible from all workspaces attached to the metastore (OPEN) or only from the workspaces bound to it (ISOLATED). It cannot be set when creating a catalog; change it with the update method and manage the bound workspaces with the workspace bindings API. See Workspace-catalog binding.
OPENISOLATED
- effective_predictive_optimization_flagobject
Indicates the predictive optimization setting that is in effect for the catalog once inherited values are resolved.
Show child attributesHide child attributes
- valuestringRequired
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
Indicates the provisioning status of the catalog. It is present only for catalogs that are provisioned asynchronously.
Show child attributesHide child attributes
- statestring
The provisioning state of the resource.
PROVISIONINGACTIVEFAILEDDELETINGUPDATINGDEGRADED
- full_namestring
The full name of the catalog. Corresponds with the name field.
- securable_typestring
The securable type is always CATALOG for a catalog.
Show 24 possible values
CATALOGSCHEMATABLESTORAGE_CREDENTIALEXTERNAL_LOCATIONFUNCTIONSHAREPROVIDERRECIPIENTCLEAN_ROOMMETASTOREPIPELINEVOLUMECONNECTIONCREDENTIALEXTERNAL_METADATASTAGING_TABLEMODELMODEL_SERVICEMCP_SERVICEMODEL_PROVIDER_SERVICEAGENT_SERVICEBetaSKILLBetaFEATURE
- custom_max_retention_hoursint64Public Preview
Dropped objects in the catalog remain recoverable for this number of hours before they are permanently purged. The value applies to standard catalogs only, must be 0 or within the range allowed for the metastore, and is inherited by schemas and tables that do not set their own value.
- managed_encryption_settingsobject
Customer-managed key (CMK) settings control the encryption at rest of the catalog's managed 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_idstringRequired
- azure_cmk_access_connector_idstring
- azure_cmk_managed_identity_idstring
- propertiesobjectRequired
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.
Delete a catalog GA
DELETE
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_argstringRequiredpath
The name of the catalog.
- forcebooleanquery
Force deletion even if the catalog is not empty.