1fanwang commented on code in PR #3769:
URL: https://github.com/apache/iceberg-python/pull/3769#discussion_r3739934581
##########
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:
Good catch, fixed in 8abb5b5. That paragraph described an earlier draft
where a pick was fast-forwarded whenever the table had not moved. The
implementation follows Java: appends are always replayed, so the wap trail is
recorded either way, and fast-forward is the fallback for a non-append whose
parent is current.
--
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]
