Update a catalog

The Lakehouse runtime catalog lets you modify the properties of existing catalog endpoints in borderless Lakehouse.

For Apache Iceberg REST catalog endpoints, you can update the credential mode, default warehouse location, and catalog type. For example, you can upgrade a single-bucket catalog to a multiple-bucket catalog (recommended) so that your catalog can span multiple storage buckets.

Before you begin

  1. Read About the Lakehouse runtime catalog to understand how the Lakehouse runtime catalog works and the limitations for the service.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

Required roles

To get the permissions that you need to update a catalog, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Update a catalog

You can update a catalog using the Google Cloud console, gcloud, or the REST API. To update a federated catalog for cross-cloud data access, see the setup guide for your data source. For example, see AWS Glue Data Catalog.

Console

  1. In the Google Cloud console, go to the Lakehouse page.

    Go to Lakehouse

  2. Click the name of your catalog.

  3. On the Catalog details page, depending on what you want to update, do one of the following:

    • Edit catalog authentication: in the Authentication method section, click  Edit catalog authentication. In the dialog, select End-user credentials or Credential vending mode, and then click Save.
    • Set or update bucket permissions: if your catalog uses credential vending mode, go to the Authentication method section. For a multiple-bucket catalog, click Set permissions for buckets. For a single-bucket catalog, click Set bucket permissions. In the confirmation dialog, click Confirm.
    • Convert to a multiple-bucket catalog or add buckets: to upgrade a single-bucket catalog or associate additional storage buckets, use the gcloud biglake iceberg catalogs update command on the gcloud tab or the REST API on the REST tab.

gcloud

Option 1: Update catalog properties

To update catalog properties (such as description or restricted locations), run the gcloud biglake iceberg catalogs update command:

gcloud biglake iceberg catalogs update CATALOG_ID \
    --project="PROJECT_ID" \
    [--description="DESCRIPTION"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--restricted-locations="RESTRICTED_LOCATIONS"]

Replace the following:

  • CATALOG_ID: the ID of your Lakehouse runtime catalog.
  • PROJECT_ID: your Google Cloud project ID.
  • DESCRIPTION: (Optional) a description for the catalog.
  • CREDENTIAL_MODE: (Optional) the authentication method. Use end-user for End-user credentials or vended-credentials for Credential vending mode.
  • RESTRICTED_LOCATIONS: (Optional) a comma-separated list of additional allowed storage buckets or paths. Caution: If you specify multiple overlapping paths or buckets, this configuration can lead to metadata conflicts, accidental data overwrites, or security issues like permission leakage.

Option 2: Upgrade a single-bucket catalog to multiple-bucket catalog (recommended)

To upgrade an existing single-bucket catalog to a multiple-bucket catalog (recommended), run the gcloud biglake iceberg catalogs update command and set the --catalog-type parameter to biglake:

gcloud biglake iceberg catalogs update CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake"

REST

Option 1: Update catalog properties

To modify a catalog's properties (such as its description) using the REST API, make a PATCH request to the UpdateIcebergCatalog endpoint with the appropriate updateMask:

PATCH /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/CATALOG_ID?updateMask=description

The request body must contain an IcebergCatalog JSON payload with the fields to update:

{
  "description": "Updated catalog description"
}

Option 2: Upgrade a single-bucket catalog to multiple-bucket catalog (recommended)

To upgrade its type using the REST API, make a PATCH request to the UpdateIcebergCatalog endpoint with the catalogType in the updateMask:

PATCH /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/CATALOG_ID?updateMask=catalog_type

The request body must contain an IcebergCatalog JSON payload with the new catalog type:

{
  "catalog_type": "CATALOG_TYPE_BIGLAKE"
}

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • CATALOG_ID: the ID of your Lakehouse runtime catalog.

Note: After upgrading to a multiple-bucket catalog, update your client query engine configurations (such as Spark or Trino) to specify the warehouse path using the bl:// format: bl://projects/PROJECT_ID/catalogs/CATALOG_ID.