Register a table

Registering an existing Apache Iceberg table integrates its metadata into the Lakehouse runtime catalog, making table data available for querying and management within a namespace. This process differs from table creation, which initializes a new, empty table structure and its associated storage.

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

  3. Set up the Lakehouse runtime catalog with the Apache Iceberg REST catalog endpoint.

Required roles

To get the permissions that you need to register a table, ask your administrator to grant you the following IAM roles on your project and storage bucket:

  • Register a table:
    • BigLake Admin (roles/biglake.admin) - your project
    • Storage Admin (roles/storage.admin) - the target Cloud Storage bucket

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.

Register a table

Register an existing Iceberg table.

gcloud

To register a table using gcloud, run the gcloud biglake iceberg tables register command.

gcloud biglake iceberg tables register TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --metadata-location="METADATA_LOCATION" \
    [--overwrite]

Replace the following:

  • TABLE_NAME: the name to assign to the registered table.
  • PROJECT_ID: the Google Cloud project ID.
  • CATALOG_ID: the catalog ID.
  • NAMESPACE_NAME: the catalog namespace name.
  • METADATA_LOCATION: the Cloud Storage URI of the latest metadata JSON file for the table, for example, gs://my-bucket/path/to/metadata/00001.metadata.json.
  • --overwrite: (Optional) Overwrite the table if it already exists.

REST

To register an Iceberg table using the REST API, make a POST request to the RegisterIcebergTable endpoint:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/register

The request body must contain a JSON payload with the following structure:

{
  "name": "TABLE_NAME",
  "metadata-location": "METADATA_LOCATION",
  "overwrite": OVERWRITE
}

Replace the following:

  • PROJECT_ID: the Google Cloud project ID.
  • CATALOG_ID: the catalog ID.
  • NAMESPACE_NAME: the catalog namespace name.
  • TABLE_NAME: the name of the registered table.
  • METADATA_LOCATION: the Cloud Storage URI of the latest metadata JSON file for the table.
  • OVERWRITE: true to overwrite if the table exists, otherwise false.

What's next