stevenzwu opened a new pull request, #16294: URL: https://github.com/apache/iceberg/pull/16294
## Summary Adds a v4 spec requirement that a snapshot's `timestamp-ms` must be strictly greater than the parent snapshot's `timestamp-ms` on the same branch, and documents the Lamport-clock style fast-forward writers must use when the wall clock would not satisfy that constraint. - `format/spec.md` Snapshots section: notes the v4-only requirement directly under the snapshot field table. - `format/spec.md` Appendix E: adds a new `Version 4` subsection (above `Version 3`) listing the snapshot-timestamp rule. This is the first v4 entry in Appendix E and is intentionally minimal\u2014other v4 changes (row-level timestamp, etc.) can be appended as they land. No table or schema fields are added. v1\u2013v3 semantics are unchanged. ## Why The v4 row-level `_last_updated_timestamp_ms` metadata column is inherited from each manifest entry's commit timestamp, which in turn comes from the snapshot's `timestamp-ms`. Time-travel queries and \"last updated\" semantics on that column rely on `timestamp-ms` being monotonically increasing with sequence number; otherwise a brief backward jump in the writer's wall clock can produce snapshots that appear out-of-order in time but in-order in sequence. Enforcing monotonicity at write time keeps the two orderings consistent without requiring readers to defensively clamp values. The Lamport-style fast-forward (`max(now, parent.timestamp-ms + 1)`) keeps commits unblocked when the wall clock has drifted: it advances by the minimum amount required, leaving steady-state behavior unchanged when the clock is healthy. ## Companion PR Reference implementation in `SnapshotProducer` is proposed in apache/iceberg#16293. ## Test plan - [x] `format/spec.md` renders correctly (note added to the v1\u2013v3 Snapshots tab; new `Version 4` subsection in Appendix E above `Version 3`) - [ ] Spec review Made with [Cursor](https://cursor.com) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
