Alter a table

Altering a table lets you evolve the schema (such as adding columns) and update table metadata properties.

Modifications are managed by the Lakehouse runtime catalog and committed via the open-source Iceberg REST Catalog API specification (POST /v1/{prefix}/namespaces/{namespace}/tables/{table} for CommitTable/UpdateIcebergTable).

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 alter a table, ask your administrator to grant you the following IAM roles on your project and storage bucket:

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

Alter a table

Add a column to the table:

Console

  1. In the Google Cloud console, go to Lakehouse.

    Go to Lakehouse

  2. Select an existing catalog or create one if you do not have one.

  3. In the Namespace details table, select a table and expand the menu options.

  4. Click Edit.

  5. Update the table values in the dialog.

  6. Click Save.

Spark 

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Trino 

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

REST

To commit changes to an Iceberg table using the REST API, make a POST request to the UpdateIcebergTable (CommitTable) endpoint:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/tables/TABLE_NAME

The request body must contain a valid Iceberg CommitTableRequest JSON payload defining the base requirement and the list of metadata updates to apply.

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • CATALOG_ID: the ID of your Lakehouse runtime catalog.
  • NAMESPACE_NAME: the name of your catalog namespace.
  • TABLE_NAME: the name of your Iceberg table.

What's next