Create a table

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

If you don't 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.

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

Table capabilities and support

When using tables in the Lakehouse runtime catalog, it's helpful to understand the different table types and their opt-in capabilities. To learn more about using Apache Iceberg tables specifically, see Overview of Apache Iceberg tables.

Supported Iceberg tables

Only Apache Iceberg V2 (GA) and V3 (Preview) tables are supported. Iceberg V1 tables aren't supported. To upgrade existing V1 tables, see Upgrade Iceberg V1 tables to V2.

Use table options (Preview)

You can opt in to use BigQuery managed capabilities, such as BigQuery Data Manipulation Language (DML) and automatic table management, by configuring specific table properties. These features are enabled in different ways depending on where the table is created:

  • From BigQuery: BigQuery DML and automatic table management are enabled by default.
  • From open source engines: To opt-in, you must explicitly configure table properties. See Configure table options for more information.

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;")

Replace the following values:

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

To enable read/write interoperability and table management (preview), add the properties to the TBLPROPERTIES clause:

TBLPROPERTIES (
  'gcp.biglake.bigquery-dml.enabled' = true,
  'gcp.biglake.table-management.enabled' = true
)

Trino 

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

Replace the following values:

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

To enable read/write interoperability and table management (Preview), add these properties to the WITH clause:

WITH (
  "gcp.biglake.bigquery-dml.enabled" = 'true',
  "gcp.biglake.table-management.enabled" = 'true'
)

gcloud

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

gcloud biglake iceberg tables create \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --create-from-file="TABLE_DEFINITION_FILE"

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • CATALOG_ID: the ID of your catalog.
  • NAMESPACE_NAME: the name of your catalog namespace.
  • TABLE_DEFINITION_FILE: the path to a JSON file containing the Iceberg table definition.

BigQuery

To create an Apache Iceberg table in the Lakehouse runtime catalog from BigQuery, use the following GoogleSQL CREATE TABLE statement. When you create a table from BigQuery, BigQuery DML and automatic table management are enabled by default.

CREATE TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME` (id int, data string);

Replace the following:

  • PROJECT_ID: your Google Cloud project ID
  • CATALOG_ID: your Lakehouse runtime catalog ID
  • NAMESPACE: your Iceberg namespace name
  • TABLE_NAME: a name for your Iceberg table

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 catalog.
  • NAMESPACE_NAME: the name of your catalog namespace.

What's next