Create a table

Creating an Apache Iceberg table registers the table metadata within a namespace in the Lakehouse runtime catalog.

If you do not specify an explicit storage location at the namespace or table level during table creation, the system automatically constructs the table's metadata and data directories under the catalog's default location (derived from the catalog's base Cloud Storage bucket) by appending the namespace and table identifiers.

In addition to query engine integrations, the Lakehouse runtime catalog implements the open-source Iceberg REST Catalog API specification (POST /v1/{prefix}/namespaces/{namespace}/tables), allowing compatible REST clients to create tables directly.

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

  • All:
    • 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.

Create a table

Create an Iceberg table.

Console

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

    Go to Lakehouse

  2. Select an existing catalog or create one if you don't have one.

  3. In the menu bar, click +Create Table.

  4. For Table format, select Iceberg.

  5. For Table name, enter a unique table name.

  6. Click Create.

Your table appears on the Namespace details page.

Spark 

spark.sql("CREATE TABLE NAMESPACE_NAME.TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Replace the following values:

  • NAMESPACE_NAME: the name of your namespace
  • TABLE_NAME: a name for your table

Trino 

CREATE TABLE SCHEMA_NAME.TABLE_NAME (id int, data varchar);

DESCRIBE SCHEMA_NAME.TABLE_NAME;

Replace the following values:

  • SCHEMA_NAME: the name of your schema
  • TABLE_NAME: a name for your table

If you use BigQuery catalog federation with Trino, you can't specify a location for the table. The schema's default location is always used.

REST

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

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

The request body must contain a valid Iceberg CreateTableRequest JSON payload defining the table schema, partition spec, and initial properties.

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.

What's next