Query a table

Querying a table reads data from the underlying Cloud Storage files using the metadata managed by the Lakehouse runtime catalog.

You can run queries from open source engines like Spark and Trino, or directly from BigQuery using a four-part table name syntax (P.C.N.T syntax).

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

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

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.