The Lakehouse runtime catalog lets you analyze Apache Iceberg
tables stored in Cloud Storage without moving or duplicating data. You can
run SQL queries from open source engines such as Apache Spark and
Trino, or directly from BigQuery using a four-part **P.C.N.T**
(**Project.Catalog.Namespace.Table**) table name, including historical queries
using time travel.

## Before you begin

1.
   [Verify that billing is enabled for your Google Cloud project](https://docs.cloud.google.com/billing/docs/how-to/verify-billing-enabled.md.txt#confirm_billing_is_enabled_on_a_project).

2.


   Enable the BigLake API, if it is not already enabled.


   **Roles required to enable APIs**


   To enable APIs, you need the `serviceusage.services.enable` permission. If you
   created the project, then you likely already have this permission through the
   Owner role (`roles/owner`). Otherwise, you can get this permission through the
   Service Usage Admin role (`roles/serviceusage.serviceUsageAdmin`).
   [Learn how to grant roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

   [Enable the API](https://console.cloud.google.com/apis/enableflow?apiid=biglake.googleapis.com)
3. [Set up the Lakehouse runtime catalog](https://docs.cloud.google.com/lakehouse/docs/set-up-lakehouse-iceberg-rest-catalog.md.txt) with the Apache Iceberg REST catalog endpoint.

### Required roles


To get the permissions that
you need to query a table,

ask your administrator to grant you the
following IAM roles on your project and storage bucket:

- Read table data in [credential vending mode](https://docs.cloud.google.com/lakehouse/docs/credential-vending.md.txt): BigLake Viewer (`roles/biglake.viewer`) - 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


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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](https://docs.cloud.google.com/lakehouse/docs/lakehouse-tables). To learn more about using
Apache Iceberg tables specifically, see [Overview of Apache Iceberg
tables](https://docs.cloud.google.com/lakehouse/docs/manage-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](https://docs.cloud.google.com/lakehouse/docs/update-tables).

**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](https://docs.cloud.google.com/lakehouse/docs/table-options) for more information.

When querying tables from BigQuery, you can access standard
Iceberg tables as well as tables enabled for BigQuery managed
capabilities. See [Configure table
options](https://docs.cloud.google.com/lakehouse/docs/table-options) for detailed instructions.

## Query a table

Select all data from the table:

### Spark

    spark.sql("SELECT * FROM TABLE_NAME;").show()

### Trino

    SELECT * FROM TABLE_NAME;

### BigQuery

To query Apache Iceberg tables in the
Lakehouse runtime catalog from BigQuery, use
the four-part table name in your query with the following format:
`PROJECT_ID.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`.

    SELECT * FROM `PROJECT_ID.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Replace the following:

- `PROJECT_ID`: the ID of the
  Google Cloud project that owns the catalog in the
  Lakehouse runtime catalog. The selected
  Google Cloud project in the Google Cloud console is billed for the
  query.

- `CATALOG_ID`: the ID of the
  Lakehouse runtime catalog catalog specified when the
  catalog was created. This identifier is used as the catalog name in
  BigQuery queries. For multiple-bucket catalogs, this
  identifier is the custom catalog name you specified. For single-bucket
  catalogs, this identifier matches the name of your Cloud Storage
  bucket.

- `NAMESPACE_OR_SCHEMA_NAME`: the table
  namespace if using Spark or table schema name if
  using Trino.

- `TABLE_NAME`: the name of your table.

## Query using time travel

You can query historical data from your managed Apache Iceberg tables using time
travel. You can time travel from BigQuery using the `FOR
SYSTEM_TIME AS OF` clause, or from open source engines like Spark using snapshot
IDs, timestamps, tags, or branches.

### Query by timestamp

To query data as of a specific timestamp:

### Spark

```sql
SELECT * FROM NAMESPACE.TABLE_NAME TIMESTAMP AS OF '2026-02-26 01:21:00';
```

### BigQuery

```sql
SELECT * FROM `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME` FOR SYSTEM_TIME AS OF '2026-02-26 01:21:00';
```

### Query by snapshot ID

To query data as of a specific snapshot ID:

### Spark

```sql
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 10963874102873;
```

### Query by tag

To create a tag and query data as of that tag:

### Spark

```sql
-- Create tag 'historical-snapshot'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE TAG 'historical-snapshot' AS OF VERSION 123456789012345;

-- Query by tag
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'historical-snapshot';
```

### Query by branch

To create a branch and query data as of that branch:

### Spark

```sql
-- Create branch 'audit-branch'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE BRANCH 'audit-branch' AS OF VERSION 123456789012345;

-- Query by branch
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'audit-branch';
```

## What's next

- Learn how to [alter a table](https://docs.cloud.google.com/lakehouse/docs/alter-table.md.txt).