Query a view

Querying an Apache Iceberg view lets you read curated, zero-copy results from the underlying Iceberg tables by running the SQL definition stored in the Lakehouse runtime catalog. Your compute engine loads the view definition from the catalog, resolves every referenced table and nested view, and then reads the data files in Cloud Storage.

You can query Iceberg views only from Iceberg-compatible open source engines such as Spark and Trino. BigQuery doesn't support querying Iceberg views.

Before you begin

  1. Verify that billing is enabled for your Google Cloud 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.

    Enable the API

  3. Set up the Lakehouse runtime catalog with the Apache Iceberg REST catalog endpoint.
  4. Review the limitations of Iceberg views.
  5. Create a view.

Required roles

Because your compute engine evaluates views client-side, you need permissions on the view and on every table and nested view that the view references.

To get the permissions that you need to query a view, ask your administrator to grant you the following IAM roles on your project and storage bucket:

  • Read the view and referenced tables in credential vending mode: BigLake Viewer (roles/biglake.viewer) - your project
  • Read the view and referenced tables in end-user credentials mode:
    • BigLake Viewer (roles/biglake.viewer) - your 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.

These predefined roles contain the permissions required to query a view. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to query a view:

  • Query a view:
    • biglake.views.get on the view and any nested views
    • biglake.tables.get on each Iceberg table that the view references
  • Read table data in credential vending mode: biglake.tables.getData on each Iceberg table that the view references
  • Read view metadata and table data in end-user credentials mode: storage.objects.get on the Cloud Storage bucket

You might also be able to get these permissions with custom roles or other predefined roles.

For a complete list of view permissions, see Required roles and permissions.

Query a view

Select all data from a view:

Spark

SELECT * FROM NAMESPACE_NAME.VIEW_NAME;

Replace the following:

  • NAMESPACE_NAME: the name of your namespace.
  • VIEW_NAME: the name of your view.

You can query views that contain joins, aggregations, CTEs, and nested views in the same way. For example, the following queries use the views from Create a view:

SELECT * FROM my_ns.eng_employees ORDER BY emp_id;
SELECT * FROM my_ns.employee_directory ORDER BY id;
SELECT * FROM my_ns.top_eng_employees;

Time travel and views

You can't apply a time travel clause such as TIMESTAMP AS OF or VERSION AS OF directly to a view identifier. If you need historical data, define a view whose SQL definition applies time travel to the underlying table, or use a CTE that queries the underlying table directly. For more information, see Create a view with time travel on underlying tables.

What's next