The Lakehouse runtime catalog lets you modify the properties of
existing
[catalog endpoints](https://docs.cloud.google.com/lakehouse/docs/about-lakehouse-catalogs.md.txt#configuration) 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](https://docs.cloud.google.com/lakehouse/docs/about-lakehouse-catalogs.md.txt) to understand how the Lakehouse runtime catalog works and the limitations for the service.

### Required roles


To get the permissions that
you need to update a catalog,

ask your administrator to grant you the
following IAM roles:

- All:
  - [BigLake Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/biglake.md.txt#biglake.admin) (`roles/biglake.admin`) on your project
  - [Storage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.admin) (`roles/storage.admin`) on your project


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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](https://console.cloud.google.com/biglake)
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 biglake iceberg catalogs update` command](https://docs.cloud.google.com/sdk/gcloud/reference/biglake/iceberg/catalogs/update.md.txt):

```bash
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 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](https://docs.cloud.google.com/sdk/gcloud/reference/biglake/iceberg/catalogs/update.md.txt)
and set the `--catalog-type` parameter to `biglake`:

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

> [!NOTE]
> **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`.

### 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`](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/patch.md.txt) 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:

```json
{
  "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`](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/patch.md.txt) 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:

```json
{
  "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`.