From f26fafa8acae0b526fa7946451409ff6aa68fbd0 Mon Sep 17 00:00:00 2001 From: Anurag Singh Date: Sat, 21 Nov 2026 02:35:31 +0530 Subject: [PATCH] Docs: Document scanning a branch or tag with use_ref Scanning a named reference already works through DataScan.use_ref, but it was not documented, so the audit example looked up the snapshot id manually. Add a section for use_ref and use it in the example. --- mkdocs/docs/api.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/mkdocs/docs/api.md b/mkdocs/docs/api.md index aa7c111329..78021b3d4d 100644 --- a/mkdocs/docs/api.md +++ b/mkdocs/docs/api.md @@ -1488,6 +1488,20 @@ Remove an existing branch: table.manage_snapshots().remove_branch("dev").commit() ``` +#### Scanning a branch or tag + +Use `use_ref` to scan a named branch or tag instead of the current snapshot of `main`: + +```python +# Scan the latest snapshot of the dev branch +table.scan().use_ref("dev").to_arrow() + +# Tags work the same way +table.scan().use_ref("v1.0.0").to_arrow() +``` + +This is equivalent to looking up the ref's snapshot id and passing it to `table.scan(snapshot_id=...)`. Scanning an unknown ref raises a `ValueError`. + #### Fast-forwarding a branch Fast-forward the `main` branch to the `audit-branch` branch: @@ -1577,8 +1591,7 @@ table.append(new_rows, branch="audit") # 2. AUDIT — scan the audit branch and run whatever validation your data-quality contract requires. # Nothing on `main` has changed yet, so readers of `main` still see the pre-write state. -audit_snapshot_id = table.refs()["audit"].snapshot_id -audit_data = table.scan(snapshot_id=audit_snapshot_id).to_arrow() +audit_data = table.scan().use_ref("audit").to_arrow() assert audit_data.num_rows > 0, "audit branch is empty" assert pc.all(pc.greater(audit_data["amount"], 0)).as_py(), \