Catalog

View as Markdown

GetGET /api/2.0/postgres/{name=catalogs/*}CreatePOST /api/2.0/postgres/catalogsDeleteDELETE /api/2.0/postgres/{name=catalogs/*}

Catalog object

namestring

Output only. The full resource path of the catalog.

Format: "catalogs/{catalog_id}".

uidstring

System-generated unique identifier for the catalog.

specobject

The desired state of the Catalog.

Show child attributesHide child attributes

postgres_databasestring

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.

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 associated with the catalog.

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

statusobject

The observed state of the Catalog.

Show child attributesHide child attributes

postgres_databasestring

The name of the Postgres database associated with the catalog.

projectstring

The resource path of the project associated with the catalog.

Format: projects/{project_id}.

branchstring

The resource path of the branch associated with the catalog.

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

create_timestring

A timestamp indicating when the catalog was created.

update_timestring

A timestamp indicating when the catalog was last updated.

catalog_idstring

The part of the name, chosen by the user when the resource was created.

View as Markdown

The Catalog object

{
  "name": "string",
  "uid": "string",
  "spec": {
    "postgres_database": "string",
    "create_database_if_missing": true,
    "branch": "string"
  },
  "status": {
    "postgres_database": "string",
    "project": "string",
    "branch": "string"
  },
  "create_time": "string",
  "update_time": "string",
  "catalog_id": "string"
}

Get GA

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

Get a Database Catalog.

API scopes: postgres

Parameters

namestringpath

The full resource path of the catalog to retrieve.

Format: "catalogs/{catalog_id}".

Response

Returns the Catalog object.

View as Markdown

Response

{
  "name": "string",
  "uid": "string",
  "spec": {
    "postgres_database": "string",
    "create_database_if_missing": true,
    "branch": "string"
  },
  "status": {
    "postgres_database": "string",
    "project": "string",
    "branch": "string"
  },
  "create_time": "string",
  "update_time": "string",
  "catalog_id": "string"
}

Create GA

POST /api/2.0/postgres/catalogs

Register a Postgres database in the Unity Catalog.

API scopes: postgres

Parameters

catalog_idstringquery

The ID in the Unity Catalog. It becomes the full resource name, for example "my_catalog" becomes "catalogs/my_catalog".

Request body

catalogobject

Show child attributesHide child attributes

namestring

Output only. The full resource path of the catalog.

Format: "catalogs/{catalog_id}".

uidstring

System-generated unique identifier for the catalog.

specobject

The desired state of the Catalog.

Show child attributesHide child attributes

postgres_databasestring

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.

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 associated with the catalog.

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

statusobject

The observed state of the Catalog.

Show child attributesHide child attributes

postgres_databasestring

The name of the Postgres database associated with the catalog.

projectstring

The resource path of the project associated with the catalog.

Format: projects/{project_id}.

branchstring

The resource path of the branch associated with the catalog.

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

create_timestring

A timestamp indicating when the catalog was created.

update_timestring

A timestamp indicating when the catalog was last updated.

catalog_idstring

The part of the name, chosen by the user when the resource was created.

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.

errorobjectRequired

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

Show child attributesHide child attributes

error_codestring

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

responseobjectRequired

The normal, successful response of the operation.

View as Markdown

Request

{
  "catalog": {
    "name": "string",
    "uid": "string",
    "spec": {},
    "status": {},
    "create_time": "string",
    "update_time": "string",
    "catalog_id": "string"
  }
}

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "string",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}

Delete GA

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

Delete a Database Catalog.

API scopes: postgres

Parameters

namestringpath

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.

errorobjectRequired

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

Show child attributesHide child attributes

error_codestring

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

responseobjectRequired

The normal, successful response of the operation.

View as Markdown

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "string",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}