Work with change history

Change history lets you track the history of rows appended to Apache Iceberg managed tables (formerly BigLake tables for Apache Iceberg in BigQuery). You can use the GoogleSQL APPENDS table-valued function (TVF) to view all rows appended to a table during a specified time range, such as rows added through CREATE TABLE DDL statements, INSERT and MERGE DML statements, batch load jobs, and streaming ingestion.

Apache Iceberg managed tables use BigQuery change history concepts and capabilities to let you process incremental additions made to your tables. Understanding what rows have been appended to a table can help you incrementally maintain a table replica outside of BigQuery, audit historical data additions, or trigger downstream pipelines without requiring full table scans or costly copies.

Required permissions

To view the change history on an Apache Iceberg managed table, you need the following permissions:

  • The bigquery.tables.getData permission on the table. This permission is included in the following predefined Identity and Access Management (IAM) roles:
    • roles/bigquery.dataViewer
    • roles/bigquery.dataEditor
    • roles/bigquery.dataOwner
    • roles/bigquery.admin
  • The bigquery.connections.delegate permission on the Google Cloud resource connection associated with the table. This permission is included in the BigQuery Connection User (roles/bigquery.connectionUser) role.
  • In addition, the service account associated with the Google Cloud resource connection must have the roles/storage.objectUser and roles/storage.legacyBucketReader roles on the underlying Cloud Storage bucket.

For additional permission requirements when a table uses row-level or column-level security, see Required permissions in the BigQuery change history documentation.

Limitations

Apache Iceberg managed tables support change history, and leverage the same concepts and capabilities as standard BigQuery change history. When working with change history on Apache Iceberg managed tables, the following limitations apply:

What's next

For more information, see the following BigQuery documentation: