Update a catalog

Updating a catalog (such as an Apache Iceberg REST catalog) lets you modify its properties, such as its credential mode, default warehouse location, or its underlying catalog type. For example, you can upgrade a legacy Cloud Storage bucket catalog (gs:// catalog) to a BigLake catalog (bl:// catalog).

Before you begin

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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's configuration, such as modifying its description, credential mode, or allowed locations.

Additionally, you can upgrade an existing Cloud Storage bucket catalog (legacy gs:// catalog) to a BigLake catalog (bl:// catalog). The upgraded catalog retains the original bucket's name. After the upgrade, you can associate multiple buckets and configure restricted locations.

You can update a catalog using the Google Cloud console, gcloud, or the REST API.

Console

  1. In the Google Cloud console, open the Lakehouse page.

    Go to Lakehouse

  2. In the row of the catalog that you want to update, click More catalog actions > Edit.

  3. Under Catalog configuration, modify the settings you want to update.

  4. Select Save.

gcloud

Use the gcloud beta biglake iceberg catalogs update command.

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

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.

REST

To modify a catalog or upgrade its type 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=icebergCatalog.catalogType,icebergCatalog.description

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

{
  "catalogType": "BIGLAKE",
  "description": "Updated catalog description"
}

Replace the following:

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