Schema

View as Markdown

GetGET /api/2.1/unity-catalog/schemas/{full_name_arg}ListGET /api/2.1/unity-catalog/schemasCreatePOST /api/2.1/unity-catalog/schemasUpdatePATCH /api/2.1/unity-catalog/schemas/{full_name_arg}DeleteDELETE /api/2.1/unity-catalog/schemas/{full_name_arg}

SchemaInfo object

namestring

Name of schema, relative to parent catalog.

catalog_namestring

Name of parent catalog.

ownerstring

Username of current owner of schema.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for managed tables within schema.

enable_predictive_optimizationstring

Whether predictive optimization should be enabled for this object and objects under it.

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 created, in epoch milliseconds.

updated_bystring

Username of user who last modified schema.

catalog_typestring

The type of the parent catalog.

Values: MANAGED_CATALOG, DELTASHARING_CATALOG, SYSTEM_CATALOG, INTERNAL_CATALOG, FOREIGN_CATALOG, MANAGED_ONLINE_CATALOG

storage_locationstring

Storage location for managed tables within schema.

effective_predictive_optimization_flagobject

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 of the schema.

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

Custom maximum retention period in hours for the schema.

propertiesobject

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

optionsobject

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

View as Markdown

The SchemaInfo object

{
  "name": "string",
  "catalog_name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "metastore_id": "string",
  "full_name": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "catalog_type": "string",
  "storage_location": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "schema_id": "string",
  "browse_only": true,
  "custom_max_retention_hours": 0,
  "properties": {},
  "options": {}
}

Get 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_argstringpath

Full name of the schema.

include_browsebooleanquery

Whether to include schemas in the response for which the principal can only access selective metadata for

Response

Returns the SchemaInfo object.

View as Markdown

Response

{
  "name": "string",
  "catalog_name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "metastore_id": "string",
  "full_name": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "catalog_type": "string",
  "storage_location": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "schema_id": "string",
  "browse_only": true,
  "custom_max_retention_hours": 0,
  "properties": {},
  "options": {}
}

List 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_namestringquery

Parent catalog for schemas of interest.

max_resultsint32query

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;

Constraints: <= 1000

page_tokenstringquery

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

include_browsebooleanquery

Whether to include schemas in the response for which the principal can only access selective metadata for

Response

Returns a list of SchemaInfo objects.

View as Markdown

Response

{
  "schemas": [
    {
      "name": "string",
      "catalog_name": "string",
      "owner": "string",
      "comment": "string",
      "storage_root": "string",
      "enable_predictive_optimization": "string",
      "metastore_id": "string",
      "full_name": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "catalog_type": "string",
      "storage_location": "string",
      "effective_predictive_optimization_flag": {},
      "schema_id": "string",
      "browse_only": true,
      "custom_max_retention_hours": 0,
      "properties": {},
      "options": {}
    }
  ],
  "next_page_token": "string"
}

Create 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

namestring

Name of schema, relative to parent catalog.

catalog_namestring

Name of parent catalog.

ownerstring

Username of current owner of schema.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for managed tables within schema.

enable_predictive_optimizationstring

Whether predictive optimization should be enabled for this object and objects under it.

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 created, in epoch milliseconds.

updated_bystring

Username of user who last modified schema.

catalog_typestring

The type of the parent catalog.

Values: MANAGED_CATALOG, DELTASHARING_CATALOG, SYSTEM_CATALOG, INTERNAL_CATALOG, FOREIGN_CATALOG, MANAGED_ONLINE_CATALOG

storage_locationstring

Storage location for managed tables within schema.

effective_predictive_optimization_flagobject

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 of the schema.

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

Custom maximum retention period in hours for the schema.

propertiesobject

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.

View as Markdown

Request

{
  "name": "string",
  "catalog_name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "metastore_id": "string",
  "full_name": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "catalog_type": "string",
  "storage_location": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "schema_id": "string",
  "browse_only": true,
  "custom_max_retention_hours": 0,
  "properties": {},
  "options": {}
}

Response

{
  "name": "string",
  "catalog_name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "metastore_id": "string",
  "full_name": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "catalog_type": "string",
  "storage_location": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "schema_id": "string",
  "browse_only": true,
  "custom_max_retention_hours": 0,
  "properties": {},
  "options": {}
}

Update 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_argstringpath

Full name of the schema.

Request body

new_namestring

New name for the schema.

namestring

Name of schema, relative to parent catalog.

catalog_namestring

Name of parent catalog.

ownerstring

Username of current owner of schema.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for managed tables within schema.

enable_predictive_optimizationstring

Whether predictive optimization should be enabled for this object and objects under it.

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 created, in epoch milliseconds.

updated_bystring

Username of user who last modified schema.

catalog_typestring

The type of the parent catalog.

Values: MANAGED_CATALOG, DELTASHARING_CATALOG, SYSTEM_CATALOG, INTERNAL_CATALOG, FOREIGN_CATALOG, MANAGED_ONLINE_CATALOG

storage_locationstring

Storage location for managed tables within schema.

effective_predictive_optimization_flagobject

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 of the schema.

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

Custom maximum retention period in hours for the schema.

propertiesobject

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.

View as Markdown

Request

{
  "new_name": "string",
  "name": "string",
  "catalog_name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "metastore_id": "string",
  "full_name": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "catalog_type": "string",
  "storage_location": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "schema_id": "string",
  "browse_only": true,
  "custom_max_retention_hours": 0,
  "properties": {},
  "options": {}
}

Response

{
  "name": "string",
  "catalog_name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "enable_predictive_optimization": "string",
  "metastore_id": "string",
  "full_name": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "catalog_type": "string",
  "storage_location": "string",
  "effective_predictive_optimization_flag": {
    "value": "string",
    "inherited_from_type": "string",
    "inherited_from_name": "string"
  },
  "schema_id": "string",
  "browse_only": true,
  "custom_max_retention_hours": 0,
  "properties": {},
  "options": {}
}

Delete 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_argstringpath

Full name of the schema.

forcebooleanquery

Force deletion even if the schema is not empty.

View as Markdown

Response

{}