Copilot commented on code in PR #3769:
URL: https://github.com/apache/iceberg-python/pull/3769#discussion_r3739269753
##########
mkdocs/docs/api.md:
##########
@@ -1483,6 +1483,38 @@ Remove an existing branch:
table.manage_snapshots().remove_branch("dev").commit()
```
+### Write-Audit-Publish
+
+Stage a write on a branch, validate it, then publish it to the table with
+`cherry_pick_snapshot`. The staged data is invisible to readers of the table
until it is
+published.
+
+```python
+# Write: stage the changes on an audit branch
+table.manage_snapshots().create_branch(
+ snapshot_id=table.metadata.current_snapshot_id,
+ branch_name="audit-2024-01-15",
+).commit()
+
+table = catalog.load_table("db.table")
+table.append(new_rows, branch="audit-2024-01-15",
snapshot_properties={"wap.id": "etl-2024-01-15"})
+
+# Audit: validate the staged data without affecting readers of the table
+table = catalog.load_table("db.table")
+staged = table.metadata.refs["audit-2024-01-15"].snapshot_id
+assert len(table.scan(snapshot_id=staged).to_arrow()) > 0
+
+# Publish: replay the staged changes onto the current table state
+table.manage_snapshots().cherry_pick_snapshot(staged).commit()
+```
+
+The published snapshot records `source-snapshot-id`, and `published-wap-id`
when the staged
+snapshot carried a `wap.id`. A given `wap.id` can only be published once.
+
+If the table has not changed since the branch was cut, the branch is
fast-forwarded rather than
+replayed. Picking a snapshot that is already an ancestor of the current state
does nothing. Only
+append snapshots can be replayed; anything else raises.
Review Comment:
The Write-Audit-Publish docs say an unchanged table is “fast-forwarded
rather than replayed,” and that “anything else raises.” This contradicts the
implementation/tests where append snapshots are always replayed (even when the
picked snapshot’s parent is current) and non-append snapshots can be
fast-forwarded when their parent is current. Please update this paragraph to
match the actual semantics of `ManageSnapshots.cherry_pick_snapshot`.
--
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]
