Skip to content

feat(scan): support scanning a branch or tag with TableScanBuilder::use_ref - #3691

Open
viirya wants to merge 1 commit into
apache:mainfrom
viirya:feat-scan-use-ref
Open

viirya wants to merge 1 commit into
apache:mainfrom
viirya:feat-scan-use-ref

Conversation

@viirya

@viirya viirya commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Which issue does this PR close?

What changes are included in this PR?

Adds TableScanBuilder::use_ref(name), the counterpart of Java's SnapshotScan.useRef. It is the only new public item: the ref map is crate-private, so callers cannot make the branch/tag schema choice themselves.

  • A tag scans its snapshot with that snapshot's schema; a branch, including main, scans with the table's current schema (SnapshotUtil.schemaFor(Table, String)).
  • use_ref("main") reads the current snapshot, so it also works on a table with no snapshots.
  • build returns DataInvalid for an unknown ref, and when snapshot_id or as_of_time is also set, in either order. snapshot_id and as_of_time keep their last-call-wins behavior with each other.

Are these changes tested?

Unit tests in scan/mod.rs, using TableTestFixture with the tagged snapshot moved to an older schema: a branch picks its snapshot with the current schema, main picks the current snapshot, a tag uses its snapshot's schema, main on an empty table, an unknown ref, and each conflicting combination.

AI Disclosure

Written with an AI assistant (Claude). Please check:

  • One deliberate difference from Java: Java's useRef("main") returns the scan unchanged, so it can be combined with useSnapshot/asOfTime. Here any ref combined with snapshot_id or as_of_time is an error, including main.
  • The method name use_ref and its impl Into<String> argument.

Copilot AI balanced review requested due to automatic review settings November 14, 2026 03:54
@viirya

viirya commented Nov 14, 2026

Copy link
Copy Markdown
Member Author

cc @szehon-ho Can you take a look? Thanks!

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

There are no active review issues for the change adding named branch and tag selection to table scans.

No open issues 🎉

What changed in this PR

Adds named branch and tag scanning to TableScanBuilder, addressing #3690 without requiring callers to access private reference metadata.

Changes:

  • Adds use_ref(name), using the current table schema for branches and the snapshot schema for tags.
  • Rejects unknown references and conflicting snapshot selections, while supporting main on empty tables.
  • Adds unit coverage and records the new method in the public API inventory.
File Description
crates/​iceberg/​src/​scan/​mod.rs Implements reference selection, schema rules, validation, and unit tests.
crates/​iceberg/​public-api.txt Records TableScanBuilder::use_ref as a public method.

Review effort: Balanced

…se_ref

Add `TableScanBuilder::use_ref`, matching Java's `SnapshotScan.useRef`.
A tag reads with the schema its snapshot was written with; a branch,
including `main`, reads with the table's current schema, as
`SnapshotUtil.schemaFor(Table, String)` does. `build` returns an error
for an unknown ref and when `snapshot_id` or `as_of_time` is also set.

Co-authored-by: Isaac <no-reply@databricks.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support scanning a branch or tag by name in TableScanBuilder

2 participants