Iceberg Time Travel is the ability to query an Iceberg table as it existed at any past snapshot or timestamp for which a snapshot has been retained. Because every write to an Iceberg table creates an immutable snapshot that references the complete set of data files active at that point, any snapshot can be read without restoring data or maintaining a separate historical copy. The query planner simply reads the manifest list for the target snapshot instead of the current snapshot.
Time travel is enabled by the immutability of Iceberg's data files. Once a Parquet file is written to object storage as part of an Iceberg commit, it is never modified. This means every past snapshot's data files remain intact and readable until explicitly deleted by the expire_snapshots maintenance procedure.
SQL Syntax
Different engines expose time travel through slightly different syntax. In Dremio and Spark, the AS OF clause is used:
-- Query by timestamp
SELECT * FROM catalog.db.orders
AS OF TIMESTAMP '2025-01-15 00:00:00';
-- Query by snapshot ID
SELECT * FROM catalog.db.orders
AS OF VERSION 8764523190123456;Trino uses the same FOR VERSION AS OF and FOR TIMESTAMP AS OF syntax. Spark DataFrames support time travel through the option("as-of-timestamp", ...) or option("snapshot-id", ...) reader options. The underlying mechanism is the same regardless of syntax: the engine uses the specified snapshot (or the snapshot whose timestamp most closely precedes the requested timestamp) as the read target.
Use Cases
- Data quality debugging: When an analyst reports unexpected numbers in a dashboard, a data engineer can time-travel to the version of the table from before the most recent pipeline run to isolate whether the problem was introduced by that run or was pre-existing.
- Regulatory audit: Compliance requirements for financial or healthcare data often require the ability to reproduce exactly what the data said on a specific date. Iceberg time travel satisfies this requirement without maintaining a separate archive system.
- Rollback validation: Before executing a rollback, engineers can query the target snapshot via time travel to confirm that it contains the expected state, reducing the risk of rolling back to the wrong version.
- AI agent reproducibility: An AI agent that ran an analysis and drew a conclusion can be re-executed against the same snapshot to reproduce its result exactly, even if the table has since been updated. This is important for audit trails of AI-generated insights.
Time Travel Limits
Time travel is only available for snapshots that have not been expired. Once expire_snapshots removes a snapshot, that point in time is no longer queryable and the data files exclusively belonging to that snapshot are deleted from storage. The snapshot retention window (typically configured via the history.expire.max-snapshot-age-ms table property) must be set to at least as long as the organization's audit and debugging requirements demand.
