Manage Lakehouse Iceberg REST catalog tables

Lakehouse for Apache Iceberg supports the creation, management, and querying of Lakehouse Iceberg REST catalog tables stored in Cloud Storage.

Managed through the Lakehouse runtime catalog, these tables are readable by BigQuery and connected open source engines. Write operations remain restricted to the specific engine that originally created the table. In addition to query engine integrations, the Lakehouse runtime catalog implements the open-source Iceberg REST Catalog API specification, allowing compatible REST clients to interact directly with table resources.

Before you begin

See the table overview to understand the different types of tables and the implications of using them.

  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 manage Lakehouse Iceberg REST catalog tables, ask your administrator to grant you the following IAM roles on your project and storage bucket:

  • Create and delete tables:
    • BigLake Admin (roles/biglake.admin) - the project
    • Storage Admin (roles/storage.admin) - the Cloud Storage bucket
  • Read table data in credential vending mode: BigLake Viewer (roles/biglake.viewer) - the project
  • Write table data in credential vending mode: BigLake Editor (roles/biglake.editor) - the project
  • Read table data in non-credential vending mode:
    • BigLake Viewer (roles/biglake.viewer) - the project
    • Storage Object Viewer (roles/storage.objectViewer) - the Cloud Storage bucket
  • Write table data in non-credential vending mode:
    • BigLake Editor (roles/biglake.editor) - the project
    • Storage Object User (roles/storage.objectUser) - the 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.

Management actions

You can perform the following management actions on your Lakehouse Iceberg REST catalog tables:

  • Create a table: Create an Apache Iceberg table within a catalog namespace using the Google Cloud console, Spark, Trino, or the Iceberg REST Catalog API (CreateIcebergTable).
  • List tables: View table identifiers within a namespace using the Google Cloud console, Spark, Trino, or the Iceberg REST Catalog API (ListIcebergTableIdentifiers).
  • Get table details: Inspect table schema, properties, and credentials using the Google Cloud console, Spark, Trino, or the Iceberg REST Catalog API (GetIcebergTable, LoadIcebergTableCredentials).
  • Insert data: Append data rows to your Iceberg tables using Spark or Trino.
  • Query a table: Execute queries against your Iceberg tables from Spark, Trino, or BigQuery using four-part table naming.
  • Alter a table: Evolve table schema and update metadata properties using the Google Cloud console, Spark, Trino, or the Iceberg REST Catalog API (UpdateIcebergTable).
  • Delete a table: Drop a table registration from the catalog without purging underlying storage files using the Google Cloud console, Spark, Trino, or the Iceberg REST Catalog API (DeleteIcebergTable).

What's next