Skip to main content
Version: Next

Time Travel

Time travel lets you query an Iceberg table as it existed at a previous snapshot. This is useful for audits, reproducible reports, backfills, debugging, and incident recovery.

How It Works​

Each commit creates a snapshot. A snapshot points to the metadata and files that define the table at that point in time. A time travel query selects one of those snapshots instead of the current one.

Snapshots remain available until retention and cleanup procedures expire them. If a snapshot has been expired, time travel to that point is no longer possible.

Query by Timestamp​

SELECT *
FROM prod.db.orders
TIMESTAMP AS OF '2026-05-01 12:00:00';

Iceberg resolves the timestamp to the latest snapshot committed at or before that time. If no older snapshot exists, the query fails.

Query by Snapshot ID​

SELECT *
FROM prod.db.orders
VERSION AS OF 8333017788700497002;

Snapshot IDs are precise and are the best choice for reproducible jobs.

Query by Branch or Tag​

SELECT *
FROM prod.db.orders
VERSION AS OF 'audit_branch';

SELECT *
FROM prod.db.orders
VERSION AS OF 'release_2026_05';

Branches and tags are named references to snapshots. They are easier to use than raw snapshot IDs when a workflow has business meaning, such as an audit branch or a monthly release tag.

Schema Selection​

Time travel to a timestamp or numeric snapshot ID normally uses the schema from that snapshot. Branch and tag queries can use engine-specific rules, so verify the behavior in your query engine before relying on schema differences.

Use Cases​

  • Compare a report before and after a pipeline change.
  • Rebuild a downstream table from a known-good snapshot.
  • Audit what data was visible at the time a decision was made.
  • Recover rows after an accidental overwrite.

Common Pitfalls​

  • Expiring snapshots too aggressively can remove the history needed for audits.
  • Time travel does not replace backups; it depends on referenced metadata and data files still existing.
  • A timestamp query can be ambiguous across time zones. Prefer snapshot IDs for automated jobs.
  • If a branch or tag name looks like a snapshot ID, engines may resolve it unexpectedly.

Key Takeaway​

Time travel is snapshot selection. It is powerful when retention is planned intentionally and dangerous when cleanup jobs delete history earlier than governance or recovery workflows expect.