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 single-bucket (gs://) catalog to a multi-bucket (bl://) catalog type (recommended). Upgrading your catalog provides significant benefits, such as allowing your catalog to span across 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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

    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.

    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

    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.

    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 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

Option 1: Update catalog properties

To update catalog properties (such as description or restricted locations), run 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"]

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 can lead to metadata conflicts, accidental data overwrites, or security issues like permission leakage.

Option 2: Upgrade a single-bucket (gs://) catalog to multi-bucket (bl://) catalog (recommended)

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

gcloud beta 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=icebergCatalog.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 (gs://) catalog to multi-bucket (bl://) 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=icebergCatalog.catalogType

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

{
  "catalogType": "BIGLAKE"
}

Replace the following:

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