unity catalog

GuideUse Unity CatalogCatalogs and schemas

Manage catalogs and schemas

Create, inspect, update, rename, and delete Unity Catalog catalogs and schemas with the Python SDK or the CLI.

Catalogs and schemas organize every asset in Unity Catalog. A catalog is the top level of the three-level namespace. It contains schemas, and a schema contains tables, volumes, functions, and registered models. For how these objects relate, see Core concepts.

Set up the client

Set up the client for your interface:

Start Python with the SDK:

uv run --with unitycatalog-client==0.7.0 python -m asyncio
catalogs.pyFull script
from unitycatalog.client import (
    ApiClient,
    CatalogsApi,
    Configuration,
    CreateCatalog,
    CreateSchema,
    SchemasApi,
    UpdateCatalog,
    UpdateSchema,
)
from unitycatalog.client.exceptions import BadRequestException, NotFoundException

config = Configuration(host="http://localhost:8080/api/2.1/unity-catalog")

Create one CatalogsApi and one SchemasApi from an open client: async with ApiClient(config) as api: catalogs = CatalogsApi(api).

Create a catalog

Give the catalog a name, plus an optional comment and key-value properties.

catalogs.pyFull script
catalog = await catalogs.create_catalog(
    CreateCatalog(
        name="retail",
        comment="Order and customer data for the retail team",
        properties={"owner_team": "retail-analytics"},
    )
)
print(catalog.name, catalog.properties)

To give the catalog its own managed storage for managed tables and volumes, also pass storage_root (--storage_root in the CLI), for example file:///srv/uc/retail or s3://bucket/retail. Without it, managed objects in this catalog need a storage root on their schema or a server-wide default.

Required privileges: CREATE_CATALOG on the metastore, or metastore ownership. With storage_root, you also need CREATE_MANAGED_STORAGE on (or ownership of) the external location that contains the path.

View catalogs

List the catalogs you can see, or fetch one by name.

catalogs.pyFull script
listed = await catalogs.list_catalogs()
print([c.name for c in listed.catalogs or []])

retail = await catalogs.get_catalog(name="retail")
print(retail.comment, retail.created_at)

Required privileges: to get a catalog, you need USE_CATALOG on it or ownership of it (or of the metastore). A list returns only the catalogs you could get.

Update a catalog

Change the comment, the properties, or the name (new_name).

catalogs.pyFull script
updated = await catalogs.update_catalog(
    name="retail",
    update_catalog=UpdateCatalog(
        comment="Curated retail data",
        properties={"owner_team": "retail-analytics", "tier": "gold"},
    ),
)
print(updated.comment, updated.properties)

Required privileges: ownership of the catalog.

Create a schema

A schema always belongs to one catalog. Like a catalog, it accepts a comment, properties, and an optional storage_root. A schema's storage root takes precedence over its catalog's.

catalogs.pyFull script
schema = await schemas.create_schema(
    CreateSchema(
        name="staging",
        catalog_name="retail",
        comment="Raw order extracts",
    )
)
print(schema.full_name)  # retail.staging

Required privileges: USE_CATALOG and CREATE_SCHEMA on the catalog, or ownership of the catalog. A storage_root needs the same external-location privilege as a catalog's.

View schemas

catalogs.pyFull script
listed_schemas = await schemas.list_schemas(catalog_name="retail")
print([s.full_name for s in listed_schemas.schemas or []])

staging = await schemas.get_schema(full_name="retail.staging")
print(staging.comment)

Required privileges: USE_CATALOG on the catalog and USE_SCHEMA on the schema, or ownership of the schema, catalog, or metastore.

Update or rename a schema

Pass new_name to rename a schema. The schema keeps its contents, and its full name changes from retail.staging to retail.sales.

catalogs.pyFull script
renamed = await schemas.update_schema(
    full_name="retail.staging",
    update_schema=UpdateSchema(new_name="sales", comment="Cleaned order data"),
)
print(renamed.full_name)  # retail.sales

Required privileges: ownership of the schema or the metastore.

Delete a schema or catalog

The server rejects a delete while the target still contains objects. It returns HTTP 400 with FAILED_PRECONDITION, and the SDK raises BadRequestException:

catalogs.pyFull script
try:
    await catalogs.delete_catalog(name="retail")
except BadRequestException as exc:
    print(f"HTTP {exc.status}: catalog still contains schemas")

Delete the contents first, starting with the innermost objects:

catalogs.pyFull script
await schemas.delete_schema(full_name="retail.sales")
await catalogs.delete_catalog(name="retail")

Or delete a catalog with everything in it:

catalogs.pyFull script
await catalogs.delete_catalog(name="retail", force=True)

Required privileges: to delete a catalog, you need ownership of the catalog or the metastore. To delete a schema, you need ownership of the schema plus USE_CATALOG, or ownership of the catalog or metastore.

Next steps