Schema
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.
MANAGED_CATALOGDELTASHARING_CATALOGSYSTEM_CATALOGINTERNAL_CATALOGFOREIGN_CATALOGMANAGED_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
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
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
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.
MANAGED_CATALOGDELTASHARING_CATALOGSYSTEM_CATALOGINTERNAL_CATALOGFOREIGN_CATALOGMANAGED_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
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.
MANAGED_CATALOGDELTASHARING_CATALOGSYSTEM_CATALOGINTERNAL_CATALOGFOREIGN_CATALOGMANAGED_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
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.