Skip to content

Commit 0af1c27

Browse files
committed
docs improvements
1 parent 5de48e5 commit 0af1c27

2 files changed

Lines changed: 22 additions & 10 deletions

File tree

‎mkdocs/docs/api.md‎

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -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
15201521
table.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

‎pyiceberg/table/update/snapshot.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -772,7 +772,6 @@ def _validate_wap_publish(metadata: TableMetadata, snapshot_id: int) -> str | No
772772

773773

774774
def _added_data_files(snapshot: Snapshot, io: FileIO) -> list[DataFile]:
775-
"""Return the data files added by the given snapshot."""
776775
added_data_files = []
777776
for manifest in snapshot.manifests(io=io):
778777
if manifest.content == ManifestContent.DATA and manifest.added_snapshot_id == snapshot.snapshot_id:

0 commit comments

Comments
 (0)