Skip to main content

Schema

View as Markdown

A schema (also called a database) is the second layer of Unity Catalog's three-level namespace and groups the tables, views, volumes, models, and functions under its parent catalog. Managed tables and volumes in the schema are stored under the schema's storage root when it has one, and otherwise under the storage of the parent catalog or the metastore.

SchemaInfo object​

A schema (also called a database) is the second layer of Unity Catalog's three-level namespace and groups the tables, views, volumes, models, and functions under its parent catalog. Managed tables and volumes in the schema are stored under the schema's storage root when it has one, and otherwise under the storage of the parent catalog or the metastore.

namestring

Name of schema, relative to parent catalog.

catalog_namestring

Name of parent catalog.

ownerstring

The user or group that owns the schema. The creator becomes the owner, and the owner can be changed only through the update method.

commentstring

User-provided free-form text description.

storage_rootstring

Managed tables and volumes in the schema 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 parent catalog's storage root, or under the metastore's root storage location when the catalog has none. Schemas in Delta Sharing catalogs cannot have a storage root, and schemas in a federated Hive metastore catalog must set one.

enable_predictive_optimizationstring

Whether predictive optimization is enabled for this schema and the objects under it. Valid values are ENABLE, DISABLE, and INHERIT, where INHERIT applies the parent catalog's setting. New schemas start as INHERIT. It cannot be set when creating a schema; use the update method instead.

metastore_idstring

Unique identifier of parent metastore.

full_namestring

Full name of schema, in form of catalog_name.schema_name.

created_atint64

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

created_bystring

Username of schema creator.

updated_atint64

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

updated_bystring

Username of user who last modified schema.

catalog_typestring

The type of the parent catalog, which the server copies from the catalog.

Values:

  • MANAGED_CATALOG
  • DELTASHARING_CATALOG
  • SYSTEM_CATALOG
  • INTERNAL_CATALOG
  • FOREIGN_CATALOG
  • MANAGED_ONLINE_CATALOG
storage_locationstring

The server derives this full storage location URL for managed tables and volumes within the schema from storage_root and the schema ID. It is absent when the schema has no storage root of its own.

effective_predictive_optimization_flagobject

Indicates the predictive optimization setting that is in effect for the schema 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.

schema_idstring

The unique identifier (UUID) that the server assigns to the schema when it is created.

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.

custom_max_retention_hoursint64Public Preview

Dropped objects in the schema remain recoverable for this number of hours before they are permanently purged. The value must be 0 or within the range allowed for the metastore. Schemas that do not set their own value inherit the parent catalog's value.

propertiesobject

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

optionsobject

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

Get a schema GA​

GET /api/2.1/unity-catalog/schemas/{full_name_arg}

Gets the specified schema within the metastore. The caller must be a metastore admin, the owner of the schema, or a user that has the USE_SCHEMA privilege on the schema.

API scopes: unity-catalog

Parameters​

full_name_argstringRequiredpath

Full name of the schema, in the form catalog_name.schema_name.

include_browsebooleanquery

Whether to return the schema 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 SchemaInfo object.

List schemas GA​

GET /api/2.1/unity-catalog/schemas

Gets an array of schemas for a catalog in the metastore. If the caller is the metastore admin or the owner of the parent catalog, all schemas for the catalog will be retrieved. Otherwise, only schemas owned by the caller (or for which the caller has the USE_SCHEMA 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​

catalog_namestringRequiredquery

Parent catalog for schemas of interest.

max_resultsint32<= 1000query

Maximum number of schemas to return. If not set, all the schemas are returned (not 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 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;
page_tokenstringquery

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

include_browsebooleanquery

Whether to include schemas for which the principal can only access selective metadata through the BROWSE privilege. Such schemas are returned with browse_only set to true.

Response​

Returns a list of SchemaInfo objects.

Create a schema GA​

POST /api/2.1/unity-catalog/schemas

Creates a new schema for catalog in the Metastore. The caller must be a metastore admin, or have the CREATE_SCHEMA privilege in the parent catalog.

API scopes: unity-catalog

Request body​

namestringRequired

Name of schema, relative to parent catalog.

catalog_namestringRequired

Name of parent catalog.

ownerstring

The user or group that owns the schema. The creator becomes the owner, and the owner can be changed only through the update method.

commentstring

User-provided free-form text description.

storage_rootstring

Managed tables and volumes in the schema 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 parent catalog's storage root, or under the metastore's root storage location when the catalog has none. Schemas in Delta Sharing catalogs cannot have a storage root, and schemas in a federated Hive metastore catalog must set one.

enable_predictive_optimizationstring

Whether predictive optimization is enabled for this schema and the objects under it. Valid values are ENABLE, DISABLE, and INHERIT, where INHERIT applies the parent catalog's setting. New schemas start as INHERIT. It cannot be set when creating a schema; use the update method instead.

metastore_idstring

Unique identifier of parent metastore.

full_namestring

Full name of schema, in form of catalog_name.schema_name.

created_atint64

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

created_bystring

Username of schema creator.

updated_atint64

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

updated_bystring

Username of user who last modified schema.

catalog_typestring

The type of the parent catalog, which the server copies from the catalog.

Values:

  • MANAGED_CATALOG
  • DELTASHARING_CATALOG
  • SYSTEM_CATALOG
  • INTERNAL_CATALOG
  • FOREIGN_CATALOG
  • MANAGED_ONLINE_CATALOG
storage_locationstring

The server derives this full storage location URL for managed tables and volumes within the schema from storage_root and the schema ID. It is absent when the schema has no storage root of its own.

effective_predictive_optimization_flagobject

Indicates the predictive optimization setting that is in effect for the schema 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.

schema_idstring

The unique identifier (UUID) that the server assigns to the schema when it is created.

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.

custom_max_retention_hoursint64Public Preview

Dropped objects in the schema remain recoverable for this number of hours before they are permanently purged. The value must be 0 or within the range allowed for the metastore. Schemas that do not set their own value inherit the parent catalog's value.

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 SchemaInfo object.

Update a schema GA​

PATCH /api/2.1/unity-catalog/schemas/{full_name_arg}

Updates a schema for a catalog. The caller must be the owner of the schema or a metastore admin. If the caller is a metastore admin, only the owner field can be changed in the update. If the name field must be updated, the caller must be a metastore admin or have the CREATE_SCHEMA privilege on the parent catalog.

API scopes: unity-catalog

Parameters​

full_name_argstringRequiredpath

Full name of the schema, in the form catalog_name.schema_name.

Request body​

new_namestring

New name for the schema.

namestringRequired

Name of schema, relative to parent catalog.

catalog_namestringRequired

Name of parent catalog.

ownerstring

The user or group that owns the schema. The creator becomes the owner, and the owner can be changed only through the update method.

commentstring

User-provided free-form text description.

storage_rootstring

Managed tables and volumes in the schema 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 parent catalog's storage root, or under the metastore's root storage location when the catalog has none. Schemas in Delta Sharing catalogs cannot have a storage root, and schemas in a federated Hive metastore catalog must set one.

enable_predictive_optimizationstring

Whether predictive optimization is enabled for this schema and the objects under it. Valid values are ENABLE, DISABLE, and INHERIT, where INHERIT applies the parent catalog's setting. New schemas start as INHERIT. It cannot be set when creating a schema; use the update method instead.

metastore_idstring

Unique identifier of parent metastore.

full_namestring

Full name of schema, in form of catalog_name.schema_name.

created_atint64

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

created_bystring

Username of schema creator.

updated_atint64

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

updated_bystring

Username of user who last modified schema.

catalog_typestring

The type of the parent catalog, which the server copies from the catalog.

Values:

  • MANAGED_CATALOG
  • DELTASHARING_CATALOG
  • SYSTEM_CATALOG
  • INTERNAL_CATALOG
  • FOREIGN_CATALOG
  • MANAGED_ONLINE_CATALOG
storage_locationstring

The server derives this full storage location URL for managed tables and volumes within the schema from storage_root and the schema ID. It is absent when the schema has no storage root of its own.

effective_predictive_optimization_flagobject

Indicates the predictive optimization setting that is in effect for the schema 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.

schema_idstring

The unique identifier (UUID) that the server assigns to the schema when it is created.

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.

custom_max_retention_hoursint64Public Preview

Dropped objects in the schema remain recoverable for this number of hours before they are permanently purged. The value must be 0 or within the range allowed for the metastore. Schemas that do not set their own value inherit the parent catalog's value.

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 SchemaInfo object.

Delete a schema GA​

DELETE /api/2.1/unity-catalog/schemas/{full_name_arg}

Deletes the specified schema from the parent catalog. The caller must be the owner of the schema or an owner of the parent catalog.

API scopes: unity-catalog

Parameters​

full_name_argstringRequiredpath

Full name of the schema, in the form catalog_name.schema_name.

forcebooleanquery

Force deletion even if the schema is not empty.