apache / apache/iceberg-rust

Add transaction actions for managing snapshot branches and tags

Open
#3,150 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Rust
Stars
1.4k
Forks
567
Avg merge
2d 2h
Merged PRs (30d)
93

Description

### Is your feature request related to a problem or challenge?

iceberg-rust already provides typed snapshot references and the underlying
`SetSnapshotRef`, `RemoveSnapshotRef`, and `RefSnapshotIdMatch` primitives,
but does not currently expose a public transaction action for standalone
branch and tag management.

In a table-management CLI, we need to create tags on existing snapshots,
rename or delete references, and move branch heads through the existing
`Transaction` and `Catalog` APIs. We would prefer to keep reference-update
semantics in iceberg-rust rather than implement custom catalog commits
in the application.

Previous related work: #1298 proposed branch/tag operations through
`ManageSnapshots` and was closed due to inactivity.

This is related to, but distinct from, #1939: that issue requests tagging
the snapshot generated by `FastAppendAction` within the same transaction.
This request concerns managing references to existing snapshots.

### Describe the solution you'd like

Add a snapshot reference action to the existing `Transaction` API, using
the typed `SnapshotReference` and `SnapshotRetention` types.

The action should support creating and deleting branches and tags,
renaming references atomically, fast-forwarding branches, and resetting
branch heads to existing snapshots. It should preserve retention policies,
protect `main` from deletion or rename, and reject attempts to create a
reference whose name is already in use.

Reference updates should use the existing `TableUpdate` and
`TableRequirement` primitives. Concurrent head changes should produce a
conflict rather than silently overwrite another writer's changes.

I have a preliminary implementation exposed through
`Transaction::update_snapshot_references()`, with tests for validation,
atomic rename, conflicts, retries, and catalog round trips. It follows the
current transaction-action structure rather than adding management logic
to the snapshot metadata types.

### Willingness to contribute

I would be willing to contribute to this feature with guidance from the Iceberg Rust community

Contributor guide

Open the contributing guide

Research direction

Start with the existing Transaction API and the preliminary Transaction::update_snapshot_references() implementation, then review the typed SnapshotReference and SnapshotRetention types plus the TableUpdate and TableRequirement primitives. Use the mentioned validation, atomic rename, conflict, retry, and catalog round-trip tests as guides. Done means reference creation, deletion, renaming, fast-forwarding, and resetting work atomically while preserving retention and rejecting protected or conflicting updates.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.