@@ -1514,21 +1514,34 @@ Fast-forward `from_branch` to point at the snapshot referenced by `to_ref`.
15141514
15151515#### Cherry-picking a snapshot
15161516
1517- Apply the changes of a snapshot from another branch, or of a staged snapshot, to ` main ` :
1517+ Cherry-pick the latest snapshot of the ` audit- branch` branch onto ` main ` :
15181518
15191519``` python
1520+ snapshot_id = table.snapshot_by_name(" audit-branch" ).snapshot_id
15201521table.manage_snapshots().cherrypick(snapshot_id).commit()
15211522```
15221523
1523- If the snapshot's parent is the current snapshot of ` main ` , ` main ` is fast-forwarded to it.
1524- Otherwise, an ` append ` snapshot is replayed as a new snapshot on top of ` main ` , which records the
1525- picked snapshot in its ` source-snapshot-id ` summary property. Other operations can only be fast-forwarded.
1524+ <!-- markdownlint-disable MD046 -- Allowing indented multi-line formatting in admonition-->
1525+
1526+ !!! info "Cherry-pick Behavior"
1527+
1528+ * Case 1: If the snapshot's parent is the current snapshot of `main`, `main` is fast-forwarded to it.
1529+ * Case 2: Otherwise, if the snapshot is an `append`, its data files are committed to `main` as a new
1530+ snapshot. The new snapshot's `source-snapshot-id` summary property is set to the picked snapshot.
1531+ * Case 3: Any other operation raises `ValidationException`.
1532+ * Picking a snapshot that is already an ancestor of `main`, or was already cherry-picked, raises
1533+ `CherrypickAncestorCommitException`.
1534+
1535+ <!-- markdownlint-enable MD046 -->
1536+
1537+ Cherry-picking can also publish a staged write-audit-publish snapshot. Stage it with a ` wap.id ` :
1538+
1539+ ``` python
1540+ table.append(df, branch = None , snapshot_properties = {" wap.id" : " nightly-2024-01-01" })
1541+ ```
15261542
1527- A snapshot written with a ` wap.id ` summary property, for example with
1528- ` table.append(df, branch=None, snapshot_properties={"wap.id": "nightly-2024-01-01"}) ` , records it
1529- as ` published-wap-id ` when picked, and a ` wap.id ` can only be published once.
1530- Picking a snapshot that is already an ancestor of ` main ` , or was already picked, raises
1531- ` CherrypickAncestorCommitException ` .
1543+ When the snapshot is replayed onto ` main ` , the new snapshot records the id as ` published-wap-id ` .
1544+ Publishing the same ` wap.id ` twice raises ` DuplicateWAPCommitException ` .
15321545
15331546#### Example Use-Case: write-audit-publish (WAP)
15341547
0 commit comments