Work with change history

Change history lets you track rows appended to Apache Iceberg managed tables (formerly BigLake tables for Apache Iceberg in BigQuery) using BigQuery change history concepts and capabilities. By using the GoogleSQL APPENDS table-valued function (TVF), you can process incremental additions over a specified time range. This helps you maintain a table replica outside of BigQuery, audit historical data additions, or trigger downstream pipelines without 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: