Skip to main content

Catalog

View as Markdown

Catalog object​

namestringIDImmutable

Output only. The full resource path of the catalog.

Format: "catalogs/{catalog_id}".

uidstringOutput only

The immutable UUID that identifies the catalog, assigned when the catalog is created.

specobjectInput only

The desired state of the Catalog. The catalog has no update method, so the spec is fixed when the catalog is created.

Show child attributesHide child attributes
postgres_databasestringImmutable

The name of the Postgres database inside the specified Lakebase project and branch to be associated with the UC catalog. This database must already exist, unless create_database_if_missing is set to true on creation. The system databases postgres, databricks_system, template0 and template1 cannot be registered.

A database can only be registered with one UC catalog at a time. To re-register a database with a different catalog, the existing catalog must be deleted first.

A child branch inherits the fact of parent's registration. This means the same-named database in a child branch cannot be registered with a second catalog while the parent's registration exists. To allow registering the database of a child branch, drop and recreate the database on the child branch. This removes the fact of parent's registration from this branch only.

Doing Point In Time Restore (PITR) prior to the moment before the Postgres DB was registered in the Catalog drops the fact of registration of the database. So the user should avoid doing so.

create_database_if_missingboolean

If set to true, the specified postgres_database is created on behalf of the calling user if it does not already exist. In this case, the calling user has a role created for them in Postgres if they do not already have one.

Defaults to false, meaning that the request fails if the specified postgres_database does not already exist.

branchstring

The resource path of the branch that holds the Postgres database. The branch must have a read-write compute endpoint.

Format: projects/{project_id}/branches/{branch_id}.

statusobjectOutput only

The observed state of the Catalog.

Show child attributesHide child attributes
postgres_databasestringOutput only

The name of the Postgres database associated with the catalog.

projectstringOutput only

The resource path of the project associated with the catalog.

Format: projects/{project_id}.

branchstringOutput only

The resource path of the branch associated with the catalog.

Format: projects/{project_id}/branches/{branch_id}.

create_timestringOutput only

A timestamp indicating when the catalog was created.

update_timestringOutput only

A timestamp indicating when the catalog was last updated.

catalog_idstringOutput only

The ID chosen when the catalog was created, which is also its name in Unity Catalog. It is the last segment of the name field.

Get a Database Catalog GA​

GET /api/2.0/postgres/{name=catalogs/*}

Gets the catalog with the given name. The status reports the Postgres database, project and branch that the catalog registers.

API scopes: postgres

Parameters​

namestringRequiredpath

The full resource path of the catalog to retrieve.

Format: "catalogs/{catalog_id}".

Response​

Returns the Catalog object.

Register a Database in UC GA​

POST /api/2.0/postgres/catalogs

Registers a Postgres database from a Lakebase project branch as a catalog in Unity Catalog, so that its schemas, tables and views are governed and discoverable through Unity Catalog. The catalog is read-only; the data stays managed through Postgres. Returns a long-running operation. Poll it until done is true; its response holds the new catalog. For an overview, see https://docs.databricks.com/aws/en/oltp/projects/register-uc.

API scopes: postgres

Parameters​

catalog_idstringRequiredquery

The ID of the catalog to create, which is also its name in Unity Catalog. It becomes the last segment of the catalog's resource name, catalogs/{catalog_id}.

Example: inventory_catalog

Request body​

namestringIDImmutable

Output only. The full resource path of the catalog.

Format: "catalogs/{catalog_id}".

specobjectInput only

The desired state of the Catalog. The catalog has no update method, so the spec is fixed when the catalog is created.

Show child attributesHide child attributes
postgres_databasestringRequiredImmutable

The name of the Postgres database inside the specified Lakebase project and branch to be associated with the UC catalog. This database must already exist, unless create_database_if_missing is set to true on creation. The system databases postgres, databricks_system, template0 and template1 cannot be registered.

A database can only be registered with one UC catalog at a time. To re-register a database with a different catalog, the existing catalog must be deleted first.

A child branch inherits the fact of parent's registration. This means the same-named database in a child branch cannot be registered with a second catalog while the parent's registration exists. To allow registering the database of a child branch, drop and recreate the database on the child branch. This removes the fact of parent's registration from this branch only.

Doing Point In Time Restore (PITR) prior to the moment before the Postgres DB was registered in the Catalog drops the fact of registration of the database. So the user should avoid doing so.

create_database_if_missingboolean

If set to true, the specified postgres_database is created on behalf of the calling user if it does not already exist. In this case, the calling user has a role created for them in Postgres if they do not already have one.

Defaults to false, meaning that the request fails if the specified postgres_database does not already exist.

branchstring

The resource path of the branch that holds the Postgres database. The branch must have a read-write compute endpoint.

Format: projects/{project_id}/branches/{branch_id}.

Response​

namestring

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean

If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobject

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes
error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values
  • UNKNOWN
  • INTERNAL_ERROR
  • TEMPORARILY_UNAVAILABLE
  • IO_ERROR
  • BAD_REQUEST
  • SERVICE_UNDER_MAINTENANCE
  • WORKSPACE_TEMPORARILY_UNAVAILABLE
  • DEADLINE_EXCEEDED
  • CANCELLED
  • RESOURCE_EXHAUSTED
  • ABORTED
  • NOT_FOUND
  • ALREADY_EXISTS
  • UNAUTHENTICATED
  • UNAVAILABLE
  • INVALID_PARAMETER_VALUE
  • ENDPOINT_NOT_FOUND
  • MALFORMED_REQUEST
  • INVALID_STATE
  • PERMISSION_DENIED
  • FEATURE_DISABLED
  • CUSTOMER_UNAUTHORIZED
  • REQUEST_LIMIT_EXCEEDED
  • RESOURCE_CONFLICT
  • UNPARSEABLE_HTTP_ERROR
  • NOT_IMPLEMENTED
  • DATA_LOSS
  • INVALID_STATE_TRANSITION
  • COULD_NOT_ACQUIRE_LOCK
  • RESOURCE_ALREADY_EXISTS
  • RESOURCE_DOES_NOT_EXIST
  • QUOTA_EXCEEDED
  • MAX_BLOCK_SIZE_EXCEEDED
  • MAX_READ_SIZE_EXCEEDED
  • PARTIAL_DELETE
  • MAX_LIST_SIZE_EXCEEDED
  • DRY_RUN_FAILED
  • RESOURCE_LIMIT_EXCEEDED
  • DIRECTORY_NOT_EMPTY
  • DIRECTORY_PROTECTED
  • MAX_NOTEBOOK_SIZE_EXCEEDED
  • MAX_CHILD_NODE_SIZE_EXCEEDED
  • SEARCH_QUERY_TOO_LONG
  • SEARCH_QUERY_TOO_SHORT
  • MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
  • PERMISSION_NOT_PROPAGATED
  • DEPLOYMENT_TIMEOUT
  • GIT_CONFLICT
  • GIT_UNKNOWN_REF
  • GIT_SENSITIVE_TOKEN_DETECTED
  • GIT_URL_NOT_ON_ALLOW_LIST
  • GIT_REMOTE_ERROR
  • PROJECTS_OPERATION_TIMEOUT
  • IPYNB_FILE_IN_REPO
  • INSECURE_PARTNER_RESPONSE
  • MALFORMED_PARTNER_RESPONSE
  • METASTORE_DOES_NOT_EXIST
  • DAC_DOES_NOT_EXIST
  • CATALOG_DOES_NOT_EXIST
  • SCHEMA_DOES_NOT_EXIST
  • TABLE_DOES_NOT_EXIST
  • SHARE_DOES_NOT_EXIST
  • RECIPIENT_DOES_NOT_EXIST
  • STORAGE_CREDENTIAL_DOES_NOT_EXIST
  • EXTERNAL_LOCATION_DOES_NOT_EXIST
  • PRINCIPAL_DOES_NOT_EXIST
  • PROVIDER_DOES_NOT_EXIST
  • METASTORE_ALREADY_EXISTS
  • DAC_ALREADY_EXISTS
  • CATALOG_ALREADY_EXISTS
  • SCHEMA_ALREADY_EXISTS
  • TABLE_ALREADY_EXISTS
  • SHARE_ALREADY_EXISTS
  • RECIPIENT_ALREADY_EXISTS
  • STORAGE_CREDENTIAL_ALREADY_EXISTS
  • EXTERNAL_LOCATION_ALREADY_EXISTS
  • PROVIDER_ALREADY_EXISTS
  • CATALOG_NOT_EMPTY
  • SCHEMA_NOT_EMPTY
  • METASTORE_NOT_EMPTY
  • PROVIDER_SHARE_NOT_ACCESSIBLE
messagestring
stack_tracestring
detailsarray of object
responseobject

The normal, successful response of the operation.

Delete a Database Catalog GA​

DELETE /api/2.0/postgres/{name=catalogs/*}

Deletes the catalog from Unity Catalog. The Postgres database and its tables remain in the branch, and the database can be registered again afterwards. Returns a long-running operation. Poll it until done is true.

API scopes: postgres

Parameters​

namestringRequiredIDImmutablepath

The full resource path of the catalog to delete.

Format: "catalogs/{catalog_id}".

Response​

namestring

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean

If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobject

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes
error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values
  • UNKNOWN
  • INTERNAL_ERROR
  • TEMPORARILY_UNAVAILABLE
  • IO_ERROR
  • BAD_REQUEST
  • SERVICE_UNDER_MAINTENANCE
  • WORKSPACE_TEMPORARILY_UNAVAILABLE
  • DEADLINE_EXCEEDED
  • CANCELLED
  • RESOURCE_EXHAUSTED
  • ABORTED
  • NOT_FOUND
  • ALREADY_EXISTS
  • UNAUTHENTICATED
  • UNAVAILABLE
  • INVALID_PARAMETER_VALUE
  • ENDPOINT_NOT_FOUND
  • MALFORMED_REQUEST
  • INVALID_STATE
  • PERMISSION_DENIED
  • FEATURE_DISABLED
  • CUSTOMER_UNAUTHORIZED
  • REQUEST_LIMIT_EXCEEDED
  • RESOURCE_CONFLICT
  • UNPARSEABLE_HTTP_ERROR
  • NOT_IMPLEMENTED
  • DATA_LOSS
  • INVALID_STATE_TRANSITION
  • COULD_NOT_ACQUIRE_LOCK
  • RESOURCE_ALREADY_EXISTS
  • RESOURCE_DOES_NOT_EXIST
  • QUOTA_EXCEEDED
  • MAX_BLOCK_SIZE_EXCEEDED
  • MAX_READ_SIZE_EXCEEDED
  • PARTIAL_DELETE
  • MAX_LIST_SIZE_EXCEEDED
  • DRY_RUN_FAILED
  • RESOURCE_LIMIT_EXCEEDED
  • DIRECTORY_NOT_EMPTY
  • DIRECTORY_PROTECTED
  • MAX_NOTEBOOK_SIZE_EXCEEDED
  • MAX_CHILD_NODE_SIZE_EXCEEDED
  • SEARCH_QUERY_TOO_LONG
  • SEARCH_QUERY_TOO_SHORT
  • MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
  • PERMISSION_NOT_PROPAGATED
  • DEPLOYMENT_TIMEOUT
  • GIT_CONFLICT
  • GIT_UNKNOWN_REF
  • GIT_SENSITIVE_TOKEN_DETECTED
  • GIT_URL_NOT_ON_ALLOW_LIST
  • GIT_REMOTE_ERROR
  • PROJECTS_OPERATION_TIMEOUT
  • IPYNB_FILE_IN_REPO
  • INSECURE_PARTNER_RESPONSE
  • MALFORMED_PARTNER_RESPONSE
  • METASTORE_DOES_NOT_EXIST
  • DAC_DOES_NOT_EXIST
  • CATALOG_DOES_NOT_EXIST
  • SCHEMA_DOES_NOT_EXIST
  • TABLE_DOES_NOT_EXIST
  • SHARE_DOES_NOT_EXIST
  • RECIPIENT_DOES_NOT_EXIST
  • STORAGE_CREDENTIAL_DOES_NOT_EXIST
  • EXTERNAL_LOCATION_DOES_NOT_EXIST
  • PRINCIPAL_DOES_NOT_EXIST
  • PROVIDER_DOES_NOT_EXIST
  • METASTORE_ALREADY_EXISTS
  • DAC_ALREADY_EXISTS
  • CATALOG_ALREADY_EXISTS
  • SCHEMA_ALREADY_EXISTS
  • TABLE_ALREADY_EXISTS
  • SHARE_ALREADY_EXISTS
  • RECIPIENT_ALREADY_EXISTS
  • STORAGE_CREDENTIAL_ALREADY_EXISTS
  • EXTERNAL_LOCATION_ALREADY_EXISTS
  • PROVIDER_ALREADY_EXISTS
  • CATALOG_NOT_EMPTY
  • SCHEMA_NOT_EMPTY
  • METASTORE_NOT_EMPTY
  • PROVIDER_SHARE_NOT_ACCESSIBLE
messagestring
stack_tracestring
detailsarray of object
responseobject

The normal, successful response of the operation.