apache / apache/iceberg

Docs: Fix tag-replacement example in Java API quickstart

Open Beginner friendly
#17,081 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
9.2k
Forks
3.5k
Avg merge
2d 16h
Merged PRs (30d)
129

Description

**Apache Iceberg version**
main @ 49b89a8c5

**Query engine**
None (Java API)

**Please describe the bug**
The "Replacing and fast forwarding branches and tags" example in `docs/docs/java-api-quickstart.md` (line 255) calls `table.manageSnapshots().replaceBranch(tag, 4)` on `tag = "audit-tag"`, a tag (already used as a tag two examples earlier via `useRef("audit-tag")`). `UpdateSnapshotReferencesOperation.replaceBranch(String, long)` (`core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java` line 99-104) requires the target ref to be a branch (`Preconditions.checkArgument(ref.isBranch(), "Ref %s is a tag not a branch", name)`), so calling it on a tag throws `IllegalArgumentException` at runtime. `ManageSnapshots` already exposes `replaceTag(String, long)` (`api/src/main/java/org/apache/iceberg/ManageSnapshots.java` line 154) for exactly this case.

**Steps to reproduce**
Copy the quickstart example as written and run it against a table with an `audit-tag` tag: the call to `replaceBranch(tag, 4)` throws `IllegalArgumentException: Ref audit-tag is a tag not a branch`.

**Additional context**
N/A.

Contributor guide

Open the contributing guide

Research direction

Open docs/docs/java-api-quickstart.md around line 255 and compare the example with ManageSnapshots.replaceTag in api/src/main/java/org/apache/iceberg/ManageSnapshots.java. Verify the reference is a tag and update the example to use the tag-specific operation; the quickstart should no longer call replaceBranch on audit-tag or throw the reported IllegalArgumentException.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Bug
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.