Snapshots & Time Travel

When you INSERT, MERGE, DELETE, or OVERWRITE an Iceberg table, the engine doesn't edit files in place. It writes new files and commits a new snapshot — a full, immutable picture of which data files make up the table at that instant — then atomically moves the table's pointer to it. Old snapshots stay valid until you explicitly expire them.

So the history of db.orders below isn't a log you have to replay — each snapshot is a queryable version of the whole table. Snapshot s1 was the initial load of 5 orders; s2 appended the 6th. The current table is s2:

-- The current (latest snapshot) state of the table
SELECT order_id, product, status, order_date
FROM db.orders
ORDER BY order_id;

Iceberg exposes the version log as ordinary tables you can query — db.orders.snapshots and db.orders.history. This is where you find the snapshot_id values you'll time-travel to. (These are Iceberg metadata tables, so they're shown here as baked output — the browser engine can't materialise them.)

SELECT committed_at, snapshot_id, parent_id, operation
FROM db.orders.snapshots
ORDER BY committed_at;

The headline feature. Append VERSION AS OF <snapshot_id> to a query and you read the table exactly as it was at that commit — no restore, no copy, just a different pointer.

SELECT * FROM db.table VERSION AS OF <snapshot_id>;
SELECT * FROM db.table VERSION AS OF '<branch-or-tag-name>';
-- also spelled: FOR SYSTEM_VERSION AS OF <snapshot_id>

Query the table at the earlier snapshot s1 — before the USB-C Cable order existed. Same table, older version, five rows:

SELECT order_id, product, status
FROM db.orders VERSION AS OF 2937501846267394851;   -- s1

Don't have a snapshot ID handy? Travel by wall-clock time instead. TIMESTAMP AS OF resolves to the snapshot that was current at that moment.

-- "How did orders look last Monday evening?"
SELECT count(*) AS n_orders
FROM db.orders TIMESTAMP AS OF '2025-07-21 00:00:00';

The same two dimensions — snapshot ID and timestamp — are read options on the DataFrame reader, handy inside a Spark/PySpark job:

// by snapshot id
val past = spark.read
  .option("snapshot-id", 2937501846267394851L)
  .table("db.orders")

// by timestamp (epoch millis)
val asOf = spark.read
  .option("as-of-timestamp", 1753056000000L)
  .table("db.orders")

Because snapshots form a chain, you can ask Iceberg for only the rows appended between two snapshots — the foundation of incremental pipelines (process new data without rescanning the whole table).

// rows added strictly after s1, up to and including s2
val newRows = spark.read
  .option("start-snapshot-id", 2937501846267394851L)  // s1 (exclusive)
  .option("end-snapshot-id",   5163847290183746522L)  // s2 (inclusive)
  .table("db.orders")

newRows.show()