Overview of Apache Iceberg views

Apache Iceberg views let you define open, non-materialized logical tables with SQL and use them from Iceberg-compatible engines such as Apache Spark, Trino, Apache Flink, PyIceberg, and dbt. You can use Iceberg views to build modular SQL pipelines and expose curated, zero-copy projections over Iceberg tables. Iceberg views are managed by the Lakehouse runtime catalog through the Apache Iceberg REST catalog endpoint, and they follow the Apache Iceberg view specification and the Iceberg REST OpenAPI specification.

This document refers to these views as Iceberg views.

Unlike BigQuery authorized views, Iceberg views are evaluated client-side by your compute engine. Iceberg views are catalog objects that you create, manage, and query from open source engines.

Capabilities

The following capabilities are supported:

  • Full view lifecycle: Create, replace, alter properties, list, inspect, and drop Iceberg views from Iceberg-compatible open source engines such as Apache Spark and Trino.
  • Rich view definitions: Define views with column aliases, column-level and view-level comments, custom properties, joins, aggregations, common table expressions (CTEs), UNION ALL, subqueries, nested views, and time travel on the underlying tables.
  • Flexible authentication: Use either end-user credentials or credential vending with standard Cloud Storage buckets and hierarchical namespace buckets.
  • Catalog support: Create views in multiple-bucket catalogs and single-bucket catalogs.

You can create, manage, and query Iceberg views only through Iceberg-compatible open source engines that connect to the Apache Iceberg REST catalog endpoint. For more information, see Limitations.

For Spark, use Spark 3.5 or later with the Iceberg runtime 1.6.0 or later. Use Iceberg runtime 1.10.0 or later so that Spark discovers the supported view endpoints through the catalog's GET /v1/config response. Set spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions so that Spark delegates view DDL and resolution to the Apache Iceberg REST catalog endpoint.

For Trino, use Trino 482 or later. For more information, see Trino support.

How Iceberg views work

An Iceberg view stores its SQL definition, schema, and properties in a versioned metadata.json file in Cloud Storage, under VIEW_LOCATION/metadata/. The Lakehouse runtime catalog tracks the current metadata location for each view and exposes the view through the view endpoints of the Apache Iceberg REST catalog endpoint.

Your compute engine evaluates Iceberg views client-side. When you run SELECT * FROM my_view, the engine loads the view definition from the catalog, resolves every referenced table and nested view, and then runs the query against the underlying Iceberg tables. The catalog doesn't run the query on your behalf.

Each time you replace a view with CREATE OR REPLACE VIEW, the catalog writes a new metadata.json file, appends a new version and schema to the view metadata, and preserves the view's view-uuid. The version.history.num-entries property bounds the number of retained versions. For more information, see View properties.

Tables and views share the same identifier namespace within a catalog namespace. You can't create a view with the same name as an existing table, or replace a table with a view.

Required roles and permissions

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

To get the permissions that you need to create, manage, and query Iceberg views, ask your administrator to grant you the following IAM roles on your project and storage bucket:

  • Create, replace, alter, and drop views: BigLake Editor (roles/biglake.editor) - your project
  • List and inspect view definitions: BigLake Viewer (roles/biglake.viewer) - your project
  • Query views in credential vending mode: BigLake Viewer (roles/biglake.viewer) - your project
  • Query views in end-user credentials mode:
    • BigLake Viewer (roles/biglake.viewer) - your project
    • Storage Object Viewer (roles/storage.objectViewer) - the Cloud Storage bucket
  • Write view metadata files in end-user credentials mode: Storage Object User (roles/storage.objectUser) - 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 create, manage, and query Iceberg views. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create, manage, and query Iceberg views:

  • Create a view:
    • biglake.views.create on the namespace
    • biglake.tables.get on each Iceberg table that the view references
  • List views: biglake.views.list on the namespace
  • Get view details: biglake.views.get on the view
  • Alter a view:
    • biglake.views.update on the view
    • biglake.tables.get on each Iceberg table that the new view definition references
  • Delete a view: biglake.views.delete on the 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
  • Write view metadata files in end-user credentials mode: storage.objects.create on the Cloud Storage bucket

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

The following table maps each view permission to the Apache Iceberg REST catalog endpoint operations that it authorizes:

Permission Resource Endpoint operations Included in predefined roles
biglake.views.create Namespace CreateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.get View GetIcebergView, CheckIcebergViewExists roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer
biglake.views.update View UpdateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.delete View DeleteIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.list Namespace ListIcebergViewIdentifiers roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer

For more information, see Lakehouse IAM roles.

Supported view endpoints

When an engine initializes a catalog session with GET /v1/config?warehouse=WAREHOUSE_URI, the Apache Iceberg REST catalog endpoint advertises the following view endpoints in the endpoints list. In the following table, {prefix} is projects/PROJECT_ID/catalogs/CATALOG_ID.

Method and path Operation Description Required permission
GET /v1/{prefix}/namespaces/{namespace}/views ListIcebergViewIdentifiers Lists view identifiers in the namespace. Supports pageToken and pageSize. Doesn't include tables. biglake.views.list on the namespace
POST /v1/{prefix}/namespaces/{namespace}/views CreateIcebergView Creates a view, writes the initial 00000-UUID.metadata.json file to Cloud Storage, and registers the view. biglake.views.create on the namespace
GET /v1/{prefix}/namespaces/{namespace}/views/{view} GetIcebergView Loads the current view metadata and metadata location. biglake.views.get on the view
POST /v1/{prefix}/namespaces/{namespace}/views/{view} UpdateIcebergView Validates optimistic concurrency requirements and commits updates to a new metadata.json file. biglake.views.update on the view
DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} DeleteIcebergView Removes the view from the catalog and purges its view-level Identity and Access Management (IAM) policy. biglake.views.delete on the view
HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} CheckIcebergViewExists Checks whether a view exists. biglake.views.get on the view

Management actions

You can perform the following management actions on your Iceberg views:

  • Create a view: Define a view over one or more Iceberg tables using Spark or the Apache Iceberg REST catalog endpoint (CreateIcebergView).
  • List views: List the view identifiers in a namespace using Spark or the Apache Iceberg REST catalog endpoint (ListIcebergViewIdentifiers).
  • Get view details: Inspect the schema, SQL definition, and properties of a view using Spark or the Apache Iceberg REST catalog endpoint (GetIcebergView).
  • Query a view: Run queries against a view from an Iceberg-compatible open source engine such as Spark.
  • Alter a view: Replace the view definition or update view properties using Spark or the Apache Iceberg REST catalog endpoint (UpdateIcebergView).
  • Delete a view: Drop a view from the catalog using Spark or the Apache Iceberg REST catalog endpoint (DeleteIcebergView).

Limitations

Iceberg views have the following limitations:

  • Open source engines only. You can create, manage, and query Iceberg views only from Iceberg-compatible open source engines through the Apache Iceberg REST catalog endpoint. BigQuery SQL, the bq command-line tool, the Google Cloud console, the gcloud CLI, and Terraform don't support Iceberg views.
  • Supported catalog types. Iceberg views are supported only in multiple-bucket catalogs and single-bucket catalogs. The catalog rejects view operations on BigQuery catalogs and federated catalogs with a 400 Bad Request (FAILED_PRECONDITION) error.
  • Unsupported REST view operations.
    • Renaming a view (POST /v1/{prefix}/views/rename or ALTER VIEW ... RENAME TO) isn't supported. To rename a view, create a view with the new name and then drop the original view.
    • Registering an existing view metadata.json file (registerView) isn't supported.
    • Materialized views aren't supported. Only logical Iceberg views are supported.
  • Time travel on views. You can't apply TIMESTAMP AS OF or VERSION AS OF to a view identifier. A view definition can apply time travel to the underlying tables that it queries. For more information, see Create a view with time travel on underlying tables.
  • View storage location.
    • In single-bucket catalogs, custom view locations aren't supported. The view location must match the default path NAMESPACE_LOCATION/VIEW_NAME.
    • In multiple-bucket catalogs, a custom view location must fall within the namespace's storage URI prefix and the catalog's allowed storage locations.
    • After you create a view, its storage location is immutable. Attempting to set a different location fails with a 400 Bad Request error.

View properties

Iceberg views support the view properties defined by Apache Iceberg. The following table describes how the catalog handles these properties:

Property Default value Behavior
write.metadata.compression-codec gzip By default, the catalog writes gzip-compressed .gz.metadata.json files. Set to none to write uncompressed .metadata.json files. The value is case-sensitive. You can set this property at creation time or with ALTER VIEW ... SET TBLPROPERTIES.
write.metadata.path VIEW_LOCATION/metadata Ignored for views. The catalog always writes view metadata files under VIEW_LOCATION/metadata/VERSION-UUID.metadata.json.
version.history.num-entries 10 Must be a positive integer. Bounds the number of entries that the catalog retains in the view's versions list and version-log. When a commit exceeds this limit, the catalog removes the oldest entries and always retains the current version and the versions added by the commit. The version log is intended for auditing and administrative rollback; compute engines don't support querying historical view versions with SQL.

What's next