Manage catalogs

This article shows how to view, update, and delete catalogs in Unity Catalog. A catalog contains schemas (databases), and a schema contains tables, views, volumes, models, and functions.

For more information about catalogs, see What are catalogs in Databricks? and Create catalogs. To learn how to grant and revoke access to a catalog, see Unity Catalog privileges and securable objects.

To learn how to manage a foreign catalog, a Unity Catalog object that mirrors a database in an external data system, see Manage and work with foreign catalogs.

Requirements

To view, update, or delete a catalog:

• You must have a Unity Catalog metastore linked to the workspace where you perform the task.

• The cluster that you use to run a notebook to manage a catalog must use a Unity Catalog-compliant access mode. See Access modes.

  SQL warehouses always support Unity Catalog.

Required permissions differ by task and are provided in each section that follows.

View catalog details

Permission required: Users can see metadata for all catalogs that they own or on which they have been assigned the USE CATALOG or BROWSE permission.

To view information about a catalog, you can use Catalog Explorer or a SQL command.

1. Log in to a workspace that is linked to the metastore.

2. Click Catalog.

3. In the Catalog pane, find the catalog and click its name.

   Some details are listed at the top of the page. Others can be viewed on the Schemas, Details, Permissions, and Workspaces tabs.

Run SHOW CATALOGS in a notebook or the SQL query editor to list all catalogs in a metastore or those that match a regular expression.

Run the following SQL command to get details about a catalog. Items in brackets are optional. Replace the placeholder <catalog-name>.

DESCRIBE CATALOG <catalog-name>;

Use CATALOG EXTENDED to get full details.

For more information, see DESCRIBE CATALOG.

Update a catalog

To update (or alter) a catalog, you can use Catalog Explorer or a SQL command.

Permissions required: Permissions required to update a catalog depend on the update:

• To change the owner, you must be the owner or have MANAGE and USE CATALOG on the catalog.

• To rename the catalog, you must be the owner or have MANAGE and USE CATALOG on the catalog.

• To add or update a comment or tags, you must be the owner or have MANAGE or MODIFY and USE CATALOG on the catalog.

• To grant and revoke permissions on the catalog, you must be the catalog owner, a metastore admin, or have MANAGE and USE CATALOG on the catalog.

1. Log into a workspace that is linked to the Unity Catalog metastore.

2. Click Catalog.

3. In the Catalog pane on the left, click the catalog that you want to update.

4. Use the following page elements on the catalog details page to update the catalog:

   • Overview tab: update the owner, add or update tags, add or update comments. See Manage Unity Catalog object ownership, Apply tags to Unity Catalog securable objects, and Add comments to data and AI assets.

   • Permissions tab: grant and revoke privileges on the catalog. See Manage privileges in Unity Catalog.

   • The kebab menu: Rename the catalog.

   • Create schema button: add a schema to the catalog. See Create schemas.

• To change the owner, add or update tags, and manage predictive optimization on the tables in a catalog, run the ALTER CATALOG command in a notebook or the SQL query editor. See ALTER CATALOG.

• To grant or revoke privileges, use the GRANT or REVOKE command. See GRANT and REVOKE.

• To add schemas to the catalog, see What are schemas in Databricks?.

• To rename a catalog using SQL, you must create a new catalog and move all assets into the new catalog.

Delete a catalog

To delete (or drop) a catalog, you can use Catalog Explorer or a SQL command.

Permission required: Catalog owner or MANAGE and USE CATALOG on the catalog.

You must delete all schemas in the catalog except information_schema before you can delete a catalog. This includes the auto-created default schema.

1. Log in to a workspace that is linked to the metastore.

2. Click Catalog.

3. In the Catalog pane, on the left, click the catalog you want to delete.

4. In the detail pane, click the kebab menu to the left of the Create database button and select Delete.

5. On the Delete catalog dialog, click Delete.

Run the following SQL command in a notebook or Databricks SQL editor. Items in brackets are optional. Replace the placeholder <catalog-name>.

For parameter descriptions, see DROP CATALOG.

If you use DROP CATALOG without the CASCADE option, you must delete all schemas in the catalog except information_schema before you can delete the catalog. This includes the auto-created default schema.

DROP CATALOG [ IF EXISTS ] <catalog-name> [ RESTRICT | CASCADE ]

For example, to delete a catalog named vaccine and its schemas:

DROP CATALOG vaccine CASCADE