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
- BigLake Viewer (
-
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.createon the namespace -
biglake.tables.geton each Iceberg table that the view references
-
-
List views:
biglake.views.liston the namespace -
Get view details:
biglake.views.geton the view -
Alter a view:
-
biglake.views.updateon the view -
biglake.tables.geton each Iceberg table that the new view definition references
-
-
Delete a view:
biglake.views.deleteon the view -
Query a view:
-
biglake.views.geton the view and any nested views -
biglake.tables.geton each Iceberg table that the view references
-
-
Read table data in credential vending mode:
biglake.tables.getDataon each Iceberg table that the view references -
Read view metadata and table data in end-user credentials mode:
storage.objects.geton the Cloud Storage bucket -
Write view metadata files in end-user credentials mode:
storage.objects.createon 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/renameorALTER 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.jsonfile (registerView) isn't supported. - Materialized views aren't supported. Only logical Iceberg views are supported.
- Renaming a view (
- Time travel on views. You can't apply
TIMESTAMP AS OForVERSION AS OFto 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 Requesterror.
- In single-bucket catalogs, custom view locations aren't supported. The
view location must match the default path
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
- Learn how to create a view.
- Learn how to query a view.
- Learn how to troubleshoot Iceberg views.