feat: add table branch support by brendanclement · Pull Request #3490 · lancedb/lancedb

brendanclement · 2026-06-03T00:52:15Z

Description

Adds first-class support for table branches across the Rust core and the Python and TypeScript SDKs.

Rust

use lance::dataset::refs::Ref;

// Create a branch from main and write to it — main is untouched.
let exp = table.create_branch("exp", Ref::Version(None, None)).await?;
exp.add(batches).await?;

// Reopen the branch later: check out from a table, or open it directly.
let exp = table.checkout_branch("exp").await?;
let exp = db.open_table("items").branch("exp").execute().await?;

let branches = table.list_branches().await?;
table.delete_branch("exp").await?;

Python

# Create a branch from main and write to it
branch = await table.branches.create("exp", from_ref="main")
await branch.add(data)

# Reopen the branch later: check out from a table, or open it directly.
branch = await table.branches.checkout("exp")
branch = await db.open_table("items", branch="exp")

await table.branches.list()
await table.branches.delete("exp")

TypeScript

const branches = await table.branches();

// Create a branch from main and write to it
const branch = await branches.create("exp");
await branch.add(data);

// Reopen the branch later: check out from a table, or open it directly.
const checkedOut = await branches.checkout("exp");
const opened = await db.openTable("items", undefined, { branch: "exp" });

await branches.list();
await branches.delete("exp");

Testing

Added unit tests
ran smoke tests against python and typescript sdks on local machine

Next steps

Add RemoteTable support
Add Branch Comparison support
Merge Branching support

brendanclement · 2026-06-03T00:53:01Z

@claude review once

brendanclement · 2026-06-03T05:09:22Z

@claude review once

brendanclement · 2026-06-03T06:24:04Z

@claude review once

brendanclement · 2026-06-03T17:00:17Z

@claude review once

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

mintlify · 2026-06-03T17:17:00Z

Docs PR opened: lancedb/docs#263

Added a Branches page under Table operations covering creating, listing, checking out, and deleting table branches across Python, TypeScript, and Rust.

Once this PR is merged, we'll do a second pass to capture any additional changes and update the docs PR.

brendanclement · 2026-06-03T18:19:49Z

@claude review once

wjones127

The API looks really well designed. I like this.

There are a few behavior / testing issues I think we need to address before we merge this.

wjones127 · 2026-06-03T19:33:43Z

+    #[tokio::test]
+    async fn test_as_branch_is_writable_and_tracked() {


issue(blocking): one test I would like to see is what happens to a branch handle if it's concurrently updated? Does the branch handle track new writes to the branch? Either way we go, I think the behavior should be asserted in a test.

I've added a test here to document the desired behaviour. A branch handle will track new writes to its branch at its read_consistency_interval.

wjones127 · 2026-06-03T19:39:59Z



+def test_branches(tmp_path):
+    db = lancedb.connect(tmp_path)


issue(blocking): the default for read_consistency_interval is None, which actually makes this test less useful. I would recommend setting this to zero for these kinds of tests:

Suggested change

db = lancedb.connect(tmp_path)

db = lancedb.connect(tmp_path, read_consistency_interval=timedelta(0))

good catch, changed to 0

wjones127

Excellent. Thank you!

mintlify · 2026-06-08T23:34:35Z

Docs PR opened: lancedb/docs#267

Added a Branches section to the versioning guide covering create, checkout, list, and delete across Python, TypeScript, and Rust.

### Description Stacked on #3490. Adds an optional version to branch checkout across the Rust core and the Python and TypeScript SDKs, so you can open a specific version on a branch ("version V of branch B"), not just the branch's latest version Rust ```rust // Open version 3 of branch "exp" (a read-only view): check out from an // existing table, or open it directly from the connection. let exp_v3 = table.checkout_branch("exp", Some(3)).await?; let exp_v3 = db.open_table("items").branch("exp").version(3).execute().await?; // checkout_latest re-attaches to the branch's writable HEAD. exp_v3.checkout_latest().await?; // With no branch, a version opens main at that version. let main_v3 = db.open_table("items").version(3).execute().await?; ``` Python ```python # Open version 3 of branch "exp" (a read-only view): check out from an # existing table, or open it directly from the connection. branch_v3 = await table.branches.checkout("exp", version=3) branch_v3 = await db.open_table("items", branch="exp", version=3) # checkout_latest re-attaches to the branch's writable HEAD. await branch_v3.checkout_latest() # With no branch, a version opens main at that version. main_v3 = await db.open_table("items", version=3) ``` TypeScript ```typescript // Open version 3 of branch "exp" (a read-only view): check out from an // existing table, or open it directly from the connection. const branchV3 = await (await table.branches()).checkout("exp", 3); const opened = await db.openTable("items", undefined, { branch: "exp", version: 3 }); // checkoutLatest re-attaches to the branch's writable HEAD. await branchV3.checkoutLatest(); // With no branch, a version opens main at that version. const mainV3 = await db.openTable("items", undefined, { version: 3 }); ``` ### Testing - Added unit tests (Rust, Python sync + async, TypeScript): branch-scoped resolution at a version number shared with `main` and with another branch, read-only enforcement on a pinned handle, `checkout_latest` recovery to the branch's HEAD, fork-point reads, and the nonexistent-version/branch error paths. - Ran smoke tests against the Python and TypeScript SDKs on local machine.

github-actions Bot added enhancement New feature or request Python Python SDK Rust Rust related issues labels Jun 3, 2026

brendanclement added the typescript Typescript / javascript label Jun 3, 2026