Feature Request / Improvement

Introduce a session-level configuration that automatically applies time-travel to all table references in a session, enabling time-freeze and deterministic query executions without requiring manual query modifications.

Currently, time-travel is only available by explicitly modifying queries (e.g., specifying AS OF / snapshot IDs / timestamps). A session-level configuration would allow consistent, repeatable query executions within a session without any changes to existing code.

The session-level configuration will only support time-based time-travel; there will be no support for snapshot-id–based session configuration.

Semantics & Behavior

1. Precedence of Time-Travel Configurations

If both:

• a session-level time-travel configuration, and
• an explicit table-level time-travel specification (e.g., FOR SYSTEM_TIME AS OF, snapshot ID, timestamp)

are provided, then the explicit table-level configuration takes precedence over the session-level setting.

This ensures that existing explicit time-travel usage remains fully honored and backward compatible.

2. Snapshot Expiration Behavior

The proposed enhancement does not change the existing behavior for snapshot expiration.

• If a query (via session-level time-travel) requests a timestamp or snapshot for which the underlying snapshot has been expired/removed, the query will fail with the existing exception:
  • java.lang.IllegalArgumentException

3. Impact on Writes

Session-level time-travel applies only to read operations.

• Reads: Resolved against the configured historical snapshot/timestamp for the session (unless overridden at the table level).
• Writes: Always operate on the current/latest table snapshot and are not affected by the session-level time-travel configuration.

This avoids surprising behavior for mutations and keeps write semantics aligned with current Iceberg expectations.

Query engine

Spark

Willingness to contribute

• I can contribute this improvement/feature independently
• I would be willing to contribute this improvement/feature with guidance from the Iceberg community
• I cannot contribute this improvement/feature at this time