This is an automated email from the ASF dual-hosted git repository.
fokko pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-python.git
The following commit(s) were added to refs/heads/main by this push:
new e32ba2a2 docs: Add docs for tags and branches (#2571)
e32ba2a2 is described below
commit e32ba2a202e20c8b9324d14911989b798371631a
Author: Gabriel Igliozzi <[email protected]>
AuthorDate: Sun Oct 5 17:13:43 2025 -0400
docs: Add docs for tags and branches (#2571)
<!--
Thanks for opening a pull request!
-->
<!-- In the case this PR will resolve an issue, please replace
${GITHUB_ISSUE_ID} below with the actual Github issue id. -->
<!-- Closes #${GITHUB_ISSUE_ID} -->
# Rationale for this change
Improved docs for tagging and branching to explicitly show how to create
and delete branches/tags along with their props
## Are these changes tested?
No code changes.
## Are there any user-facing changes?
No
<!-- In the case of user-facing changes, please add the changelog label.
-->
---
mkdocs/docs/api.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
diff --git a/mkdocs/docs/api.md b/mkdocs/docs/api.md
index 05a4db92..338e58b2 100644
--- a/mkdocs/docs/api.md
+++ b/mkdocs/docs/api.md
@@ -1350,6 +1350,62 @@ with table.manage_snapshots() as ms:
ms.create_branch(snapshot_id1, "Branch_A").create_tag(snapshot_id2,
"tag789")
```
+### Tags
+
+Tags are named references to snapshots that are immutable. They can be used to
mark important snapshots for long-term retention or to reference specific table
versions.
+
+Create a tag pointing to a specific snapshot:
+
+```python
+# Create a tag with default retention
+table.manage_snapshots().create_tag(
+ snapshot_id=snapshot_id,
+ tag_name="v1.0.0"
+).commit()
+
+# Create a tag with custom max reference age
+table.manage_snapshots().create_tag(
+ snapshot_id=snapshot_id,
+ tag_name="v1.0.0",
+ max_ref_age_ms=604800000 # 7 days
+).commit()
+```
+
+Remove an existing tag:
+
+```python
+table.manage_snapshots().remove_tag("v1.0.0").commit()
+```
+
+### Branching
+
+Branches are mutable named references to snapshots that can be updated over
time. They allow for independent lineages of table changes, enabling use cases
like development branches, testing environments, or parallel workflows.
+
+Create a branch pointing to a specific snapshot:
+
+```python
+# Create a branch with default settings
+table.manage_snapshots().create_branch(
+ snapshot_id=snapshot_id,
+ branch_name="dev"
+).commit()
+
+# Create a branch with retention policies
+table.manage_snapshots().create_branch(
+ snapshot_id=snapshot_id,
+ branch_name="dev",
+ max_ref_age_ms=604800000, # Max age of the branch reference (7 days)
+ max_snapshot_age_ms=259200000, # Max age of snapshots to keep (3 days)
+ min_snapshots_to_keep=10 # Minimum number of snapshots to retain
+).commit()
+```
+
+Remove an existing branch:
+
+```python
+table.manage_snapshots().remove_branch("dev").commit()
+```
+
## Table Maintenance
PyIceberg provides table maintenance operations through the
`table.maintenance` API. This provides a clean interface for performing
maintenance tasks like snapshot expiration.
