Skip to content

feat: add remote branch diff and merge client APIs#3686

Merged
jackye1995 merged 3 commits into
lancedb:mainfrom
geruh:stubbed-merge
Jul 18, 2026
Merged

feat: add remote branch diff and merge client APIs#3686
jackye1995 merged 3 commits into
lancedb:mainfrom
geruh:stubbed-merge

Conversation

@geruh

@geruh geruh commented Jul 17, 2026

Copy link
Copy Markdown
Member

This PR adds some support for diff / merge in the remote client as for local tables we stay NotSupported until lance-format/lance#7263.

This wires the two review-and-land calls against the remote REST API:

  • POST /v1/table/{id}/branches/diff
  • POST /v1/table/{id}/branches/merge

Rust gets typed results (BranchDiff, MergeBranchResult). Python returns the wire JSON, same shape as the REST response.

Merge here means promoting a branch's added columns onto main.

Behavior

  • Remote only. Local raises NotSupported.
  • A rejected merge is not an exception. HTTP 409 still returns Ok / a dict with status="rejected" and blockers in diff.mergeBlockers.
  • Unknown blocker / status codes parse as Unknown so a newer server does not break older clients.
  • MergePreview tolerates missing fields for the same reason.
  • Merge requests are not retried. 409 is final and carries the body you need.

Example

table = db.open_table("images")

table.branches.create("exp")
exp = table.branches.checkout("exp")

exp.add_columns({"tag": "cast('draft' as string)"})

diff = table.branches.diff("exp")
preview = table.branches.merge("exp", dry_run=True)
result = table.branches.merge("exp", dry_run=False)

if result["status"] == "merged":
    print("landed at", result["mainVersionAfter"])
elif result["status"] == "rejected":
    print(result["diff"]["mergeBlockers"])

Testing

cargo test -p lancedb --features remote diff_branch
cargo test -p lancedb --features remote merge_branch

Wire POST /branches/diff and /branches/merge for Rust remote + Python.
Parse 409 bodies as rejected results, tolerate unknown blocker/status
codes, and keep MergePreview forward-compatible when fields are missing.

Co-authored-by: Cursor <[email protected]>

@claude claude Bot 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.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@github-actions github-actions Bot added enhancement New feature or request Python Python SDK Rust Rust related issues labels Jul 17, 2026
@geruh

geruh commented Jul 17, 2026

Copy link
Copy Markdown
Member Author

@claude review

@dantasse dantasse left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Cool, mostly looks good. Can you add this to Typescript too?

Comment thread python/python/lancedb/table.py Outdated
----------
from_branch: str
Branch to merge from.
dry_run: bool, default True

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

what do you think about default False? (and probably updating this on the REST call too)

I get avoiding writing data unless you're very careful but after playing around with this, it feels weird (to me and the agent, or maybe I should say, to me watching the agent) that merge() without extra flags doesn't actually merge.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

+1 for dry run should be an explicit argument to turn on

@jackye1995 jackye1995 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

looks good to me! pending docs CI fix

@jackye1995
jackye1995 merged commit 65cd142 into lancedb:main Jul 18, 2026
27 of 29 checks passed
@mintlify

mintlify Bot commented Jul 18, 2026

Copy link
Copy Markdown

Docs PR opened: lancedb/docs#315

Documented the new Enterprise branch diff and merge APIs on the Branches page with Python and TypeScript examples.

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

Labels

enhancement New feature or request Python Python SDK Rust Rust related issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants