Altering an Apache Iceberg view lets you evolve the view's schema and SQL definition, or set and unset custom view properties, without changing the view's identity in the Lakehouse runtime catalog.
Renaming a view isn't supported. To rename a view, create a view with the new
name and then delete the original view. A
view's storage location is also immutable after creation, and an update that
sets a different location fails with a 400 Bad Request error.
Before you begin
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the BigLake API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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. - Set up the Lakehouse runtime catalog with the Apache Iceberg REST catalog endpoint.
- Review the limitations of Iceberg views.
- Create a view.
Required roles
To get the permissions that you need to alter a view, ask your administrator to grant you the following IAM roles on your project and storage bucket:
-
Alter a view:
BigLake Editor (
roles/biglake.editor) - your project -
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 alter a view. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to alter a view:
-
Alter a view:
-
biglake.views.updateon the view -
biglake.tables.geton each Iceberg table that the new view definition references
-
-
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.
For a complete list of view permissions, see Required roles and permissions.
Replace a view definition
Replace the schema and SQL logic of an existing view. When you replace a view,
the catalog writes a new versioned metadata.json file (for example,
00001-UUID.metadata.json), appends a new view version
and schema to the view metadata, and preserves the view's view-uuid.
Spark
CREATE OR REPLACE VIEW my_ns.eng_employees (
emp_id,
emp_name,
dept,
salary,
is_senior
)
COMMENT 'Updated Engineering view with seniority flag'
AS SELECT id, name, dept, salary, (salary >= 140000.0) AS is_senior
FROM my_ns.employees
WHERE dept = 'Engineering';
REST
To update a view using the REST API, make a POST request to the
UpdateIcebergView endpoint:
POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/views/VIEW_NAME
The request body must contain a valid Iceberg CommitViewRequest JSON
payload with the requirements and updates to apply. The catalog
validates the optimistic concurrency requirements and commits the updates
to a new metadata.json file.
Replace the following:
PROJECT_ID: your Google Cloud project ID.CATALOG_ID: the ID of your catalog.NAMESPACE_NAME: the name of your catalog namespace.VIEW_NAME: the name of your view.
Set and unset view properties
Set or remove custom properties on a view without changing its definition.
Spark
Set properties:
ALTER VIEW my_ns.eng_employees
SET TBLPROPERTIES ('tier' = 'gold', 'reviewed' = 'true');
Unset a property:
ALTER VIEW my_ns.eng_employees
UNSET TBLPROPERTIES IF EXISTS ('reviewed');
For details about how the catalog handles properties such as
write.metadata.compression-codec, see View
properties.
REST
Send a CommitViewRequest to the UpdateIcebergView endpoint with
set-properties or remove-properties updates. See Replace a view
definition for the endpoint path.
What's next
- Learn how to get view details.
- Learn how to delete a view.