Upgrade Iceberg V1 tables to V2

If you have existing version 1 (V1) Apache Iceberg tables, you must upgrade them using your query engine before using them with the Apache Iceberg REST catalog endpoint. For more information, see Alter a table.

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

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

Required roles

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

  • Upgrade table in credential vending mode: BigLake Editor (roles/biglake.editor) - the project
  • Upgrade table 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.

Upgrade a table

To upgrade an Iceberg V1 table to V2, run the following command in your query engine:

Spark 

ALTER TABLE CATALOG_NAME.SCHEMA_NAME.TABLE_NAME SET TBLPROPERTIES ('format-version'='2');

Replace the following:

  • CATALOG_NAME: the name of your catalog.
  • SCHEMA_NAME: the name of your schema.
  • TABLE_NAME: the name of your table.

What's next