Catalog
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
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
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}.
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
nameshould be a resource name ending withoperations/{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. Iftrue, the operation is completed, and eithererrororresponseis 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.
Show 81 possible values
UNKNOWNINTERNAL_ERRORTEMPORARILY_UNAVAILABLEIO_ERRORBAD_REQUESTSERVICE_UNDER_MAINTENANCEWORKSPACE_TEMPORARILY_UNAVAILABLEDEADLINE_EXCEEDEDCANCELLEDRESOURCE_EXHAUSTEDABORTEDNOT_FOUNDALREADY_EXISTSUNAUTHENTICATEDUNAVAILABLEINVALID_PARAMETER_VALUEENDPOINT_NOT_FOUNDMALFORMED_REQUESTINVALID_STATEPERMISSION_DENIEDFEATURE_DISABLEDCUSTOMER_UNAUTHORIZEDREQUEST_LIMIT_EXCEEDEDRESOURCE_CONFLICTUNPARSEABLE_HTTP_ERRORNOT_IMPLEMENTEDDATA_LOSSINVALID_STATE_TRANSITIONCOULD_NOT_ACQUIRE_LOCKRESOURCE_ALREADY_EXISTSRESOURCE_DOES_NOT_EXISTQUOTA_EXCEEDEDMAX_BLOCK_SIZE_EXCEEDEDMAX_READ_SIZE_EXCEEDEDPARTIAL_DELETEMAX_LIST_SIZE_EXCEEDEDDRY_RUN_FAILEDRESOURCE_LIMIT_EXCEEDEDDIRECTORY_NOT_EMPTYDIRECTORY_PROTECTEDMAX_NOTEBOOK_SIZE_EXCEEDEDMAX_CHILD_NODE_SIZE_EXCEEDEDSEARCH_QUERY_TOO_LONGSEARCH_QUERY_TOO_SHORTMANAGED_RESOURCE_GROUP_DOES_NOT_EXISTPERMISSION_NOT_PROPAGATEDDEPLOYMENT_TIMEOUTGIT_CONFLICTGIT_UNKNOWN_REFGIT_SENSITIVE_TOKEN_DETECTEDGIT_URL_NOT_ON_ALLOW_LISTGIT_REMOTE_ERRORPROJECTS_OPERATION_TIMEOUTIPYNB_FILE_IN_REPOINSECURE_PARTNER_RESPONSEMALFORMED_PARTNER_RESPONSEMETASTORE_DOES_NOT_EXISTDAC_DOES_NOT_EXISTCATALOG_DOES_NOT_EXISTSCHEMA_DOES_NOT_EXISTTABLE_DOES_NOT_EXISTSHARE_DOES_NOT_EXISTRECIPIENT_DOES_NOT_EXISTSTORAGE_CREDENTIAL_DOES_NOT_EXISTEXTERNAL_LOCATION_DOES_NOT_EXISTPRINCIPAL_DOES_NOT_EXISTPROVIDER_DOES_NOT_EXISTMETASTORE_ALREADY_EXISTSDAC_ALREADY_EXISTSCATALOG_ALREADY_EXISTSSCHEMA_ALREADY_EXISTSTABLE_ALREADY_EXISTSSHARE_ALREADY_EXISTSRECIPIENT_ALREADY_EXISTSSTORAGE_CREDENTIAL_ALREADY_EXISTSEXTERNAL_LOCATION_ALREADY_EXISTSPROVIDER_ALREADY_EXISTSCATALOG_NOT_EMPTYSCHEMA_NOT_EMPTYMETASTORE_NOT_EMPTYPROVIDER_SHARE_NOT_ACCESSIBLE
- messagestring
- stack_tracestring
- detailsarray of object
- responseobject
The normal, successful response of the operation.
Delete a Database Catalog GA
DELETE
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
nameshould be a resource name ending withoperations/{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. Iftrue, the operation is completed, and eithererrororresponseis 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.
Show 81 possible values
UNKNOWNINTERNAL_ERRORTEMPORARILY_UNAVAILABLEIO_ERRORBAD_REQUESTSERVICE_UNDER_MAINTENANCEWORKSPACE_TEMPORARILY_UNAVAILABLEDEADLINE_EXCEEDEDCANCELLEDRESOURCE_EXHAUSTEDABORTEDNOT_FOUNDALREADY_EXISTSUNAUTHENTICATEDUNAVAILABLEINVALID_PARAMETER_VALUEENDPOINT_NOT_FOUNDMALFORMED_REQUESTINVALID_STATEPERMISSION_DENIEDFEATURE_DISABLEDCUSTOMER_UNAUTHORIZEDREQUEST_LIMIT_EXCEEDEDRESOURCE_CONFLICTUNPARSEABLE_HTTP_ERRORNOT_IMPLEMENTEDDATA_LOSSINVALID_STATE_TRANSITIONCOULD_NOT_ACQUIRE_LOCKRESOURCE_ALREADY_EXISTSRESOURCE_DOES_NOT_EXISTQUOTA_EXCEEDEDMAX_BLOCK_SIZE_EXCEEDEDMAX_READ_SIZE_EXCEEDEDPARTIAL_DELETEMAX_LIST_SIZE_EXCEEDEDDRY_RUN_FAILEDRESOURCE_LIMIT_EXCEEDEDDIRECTORY_NOT_EMPTYDIRECTORY_PROTECTEDMAX_NOTEBOOK_SIZE_EXCEEDEDMAX_CHILD_NODE_SIZE_EXCEEDEDSEARCH_QUERY_TOO_LONGSEARCH_QUERY_TOO_SHORTMANAGED_RESOURCE_GROUP_DOES_NOT_EXISTPERMISSION_NOT_PROPAGATEDDEPLOYMENT_TIMEOUTGIT_CONFLICTGIT_UNKNOWN_REFGIT_SENSITIVE_TOKEN_DETECTEDGIT_URL_NOT_ON_ALLOW_LISTGIT_REMOTE_ERRORPROJECTS_OPERATION_TIMEOUTIPYNB_FILE_IN_REPOINSECURE_PARTNER_RESPONSEMALFORMED_PARTNER_RESPONSEMETASTORE_DOES_NOT_EXISTDAC_DOES_NOT_EXISTCATALOG_DOES_NOT_EXISTSCHEMA_DOES_NOT_EXISTTABLE_DOES_NOT_EXISTSHARE_DOES_NOT_EXISTRECIPIENT_DOES_NOT_EXISTSTORAGE_CREDENTIAL_DOES_NOT_EXISTEXTERNAL_LOCATION_DOES_NOT_EXISTPRINCIPAL_DOES_NOT_EXISTPROVIDER_DOES_NOT_EXISTMETASTORE_ALREADY_EXISTSDAC_ALREADY_EXISTSCATALOG_ALREADY_EXISTSSCHEMA_ALREADY_EXISTSTABLE_ALREADY_EXISTSSHARE_ALREADY_EXISTSRECIPIENT_ALREADY_EXISTSSTORAGE_CREDENTIAL_ALREADY_EXISTSEXTERNAL_LOCATION_ALREADY_EXISTSPROVIDER_ALREADY_EXISTSCATALOG_NOT_EMPTYSCHEMA_NOT_EMPTYMETASTORE_NOT_EMPTYPROVIDER_SHARE_NOT_ACCESSIBLE
- messagestring
- stack_tracestring
- detailsarray of object
- responseobject
The normal, successful response of the operation.