Skip to main content

System Schema

View as Markdown

A system schema of a metastore, with its current enablement state. System schemas hold Databricks-provided system tables, such as audit logs and billing usage. They live in the system catalog unless they are enabled in another supported catalog. See https://docs.databricks.com/aws/en/admin/system-tables/.

SystemSchemaInfo object​

A system schema of a metastore, with its current enablement state. System schemas hold Databricks-provided system tables, such as audit logs and billing usage. They live in the system catalog unless they are enabled in another supported catalog. See https://docs.databricks.com/aws/en/admin/system-tables/.

schemastringPublic Preview

Name of the system schema, without the catalog prefix.

statestringPublic Preview

The current enablement state of the system schema. Possible values are AVAILABLE (the schema can be enabled), ENABLE_INITIALIZED (enablement is in progress), ENABLE_COMPLETED (the schema is enabled), DISABLE_INITIALIZED (disablement is in progress), UNAVAILABLE (the schema cannot be enabled at the moment) and MANAGED (Databricks enables the schema automatically).

List system schemas Public Preview​

GET /api/2.1/unity-catalog/metastores/{metastore_id}/systemschemas

Gets an array of system schemas for a metastore. The caller must be an account admin or a metastore admin.

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​

metastore_idstringRequiredpath

The ID for the metastore in which the system schema resides.

max_resultsint32<= 1000query

Maximum number of schemas to return.

  • When set to 0, the page length is set to a server configured value (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 a value less than 0, an invalid parameter error is returned;
  • If not set, all the schemas are returned (not recommended).
page_tokenstringquery

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

Response​

Returns a list of SystemSchemaInfo objects.

Enable a system schema Public Preview​

PUT /api/2.1/unity-catalog/metastores/{metastore_id}/systemschemas/{schema}

Enables the system schema and adds it to the system catalog. The caller must be an account admin or a metastore admin.

API scopes: unity-catalog

Parameters​

metastore_idstringRequiredpath

The metastore ID under which the system schema lives.

schemastringRequiredpath

Name of the system schema, without the catalog prefix.

Example: access

Request body​

catalog_namestring

Name of the catalog in which to enable the system schema. The supported values are system and samples. If not set, the system schema is enabled in the system catalog.

Disable a system schema Public Preview​

DELETE /api/2.1/unity-catalog/metastores/{metastore_id}/systemschemas/{schema}

Disables the system schema and removes it from the system catalog. The caller must be an account admin or a metastore admin.

API scopes: unity-catalog

Parameters​

metastore_idstringRequiredpath

The metastore ID under which the system schema lives.

schemastringRequiredpath

Name of the system schema, without the catalog prefix.

Example: access