> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Branches

> Fork isolated, writable lines of table history in LanceDB. Run experiments, backfills, and index rebuilds without disturbing production reads on main.

A branch is an isolated, writable line of history forked from `main` (or from any
other branch). Anything you do on a branch (e.g., adding rows, changing the schema,
building an index) stays on that branch, so `main` keeps serving production
reads exactly as before. Branches are a natural fit when you want to:

* Experiment with a new index, schema change, or reprocessing step without
  affecting live queries on `main`.
* Run a backfill or migration you'd like to validate before applying it to
  `main`.
* Hand a collaborator a frozen point-in-time fork while you keep writing to `main`.

## How branches relate to versions and tags

Every LanceDB table already tracks a linear history of [versions](https://docs.lancedb.com/enterprise/v1-12-0/management/table.md#versioning),
and you can [tag](https://docs.lancedb.com/enterprise/v1-12-0/management/table.md#versioning-tag-based-versioning) a version or `checkout`
one to read it. Branches add the missing piece: a *separate, writable* line of
history. Where a tag is a read-only label and `checkout` is a read-only view, a
branch forks from a point in history and then evolves on its own. Creating or
checking out a branch hands you a new table handle whose reads and writes are
scoped to that branch. The [comparison table](#branches-vs-tags-vs-versions) at
the end of this page lays out when to reach for each.

> [!NOTE]
>
> Branches are supported on local and namespace-backed tables in LanceDB Embedded,
> as well as on LanceDB Enterprise tables.

## Connect to a table

The branch API is identical no matter how you connect: only the connection
itself differs between LanceDB Embedded and LanceDB Enterprise. Establish a connection (`db`) and open
a `table` (see [Ingesting data](https://docs.lancedb.com/enterprise/v1-12-0/ingestion.md)), then use the same branch calls
in every example that follows.

### LanceDB Embedded

Point LanceDB at a local directory (or an object-storage URI) to use it as an
embedded library.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
import lancedb

uri = "ex_lancedb"
db = lancedb.connect(uri)
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("ex_lancedb");
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
use lancedb::connect;

let db = connect("ex_lancedb").execute().await?;
```

### LanceDB Enterprise

Enterprise

Branching on LanceDB Enterprise works the same way as on LanceDB Embedded, apart from the differences
noted below, but you connect to your
Enterprise deployment with a `db://` URI, an API key, and your
region and endpoint. Replace the placeholders below, including `us-east-1` if your
deployment uses another region. In application code, load credentials from environment
variables or a secrets manager. Once connected, open a table and use the same branch
calls in every example that follows.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
import lancedb

db = lancedb.connect(
    uri="db://your-database",
    api_key="your-api-key",
    region="us-east-1",
    host_override="https://your-endpoint",
    sql_host_override="grpc+tls://your-sql-endpoint:10026",
)
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
const db = await lancedb.connect("db://your-database", {
  apiKey: "your-api-key",
  region: "us-east-1",
  hostOverride: "https://your-endpoint",
});
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
use lancedb::connect;

let db = connect("db://your-database")
    .api_key("your-api-key")
    .region("us-east-1")
    .host_override("https://your-endpoint")
    .execute()
    .await?;
```

## Work with branches

The lifecycle of a branch is short and predictable: fork it, write to it, reopen
it whenever you need it, and delete it once you're done. The examples below use a
small `quotes` table with three rows on `main`.

### Create a branch

Forking from `main` returns a table handle scoped to the new branch. `main` is
the reserved default source, so `create` needs only a name; to fork from
somewhere else, pass a branch name, a specific version, or both.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# Fork an isolated, writable branch from main's latest version.
# `create` returns a table handle scoped to the new branch.
branch = table.branches.create("exp")
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Fork an isolated, writable branch from main's latest version.
// `create` returns a table handle scoped to the new branch.
const branch = await branches.create("exp");
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Fork an isolated, writable branch from main's latest version.
// `create_branch` returns a table handle scoped to the new branch.
let branch = branches_table
    .create_branch("exp", Ref::Version(None, None))
    .await
    .unwrap();
```

### Write to a branch

Writes go through the branch handle and stay there: the `main` handle keeps
reporting its original row count. Listing branches returns a mapping of each
branch name to its metadata, including the version it was forked from.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# Writes land on the branch handle only; main is left untouched.
branch.add([{"id": 4, "author": "Lancelot", "quote": "For the realm!"}])
print(branch.count_rows())  # 4 rows on the branch
print(table.count_rows())  # 3 rows; main is unaffected

# List every branch, each mapped to its metadata (including its fork point).
print(table.branches.list())
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Writes land on the branch handle only; main is left untouched.
await branch.add([{ id: 4, author: "Lancelot", quote: "For the realm!" }]);
console.log(await branch.countRows()); // 4 rows on the branch
console.log(await table.countRows()); // 3 rows; main is unaffected

// List every branch, each mapped to its metadata (including its fork point).
console.log(await branches.list());
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Writes land on the branch handle only; main is left untouched.
branch
    .add(make_quotes_reader(vec![(4, "Lancelot", "For the realm!")]))
    .execute()
    .await
    .unwrap();
println!("Branch rows: {}", branch.count_rows(None).await.unwrap()); // 4
println!("Main rows: {}", branches_table.count_rows(None).await.unwrap()); // 3

// List every branch, each mapped to its metadata (including its fork point).
println!("Branches: {:?}", branches_table.list_branches().await.unwrap());
```

### Reopen a branch

A branch outlives the handle that created it. Reopen it later by name, either
from an existing table handle or straight from the connection when you open the
table. Both routes give you a writable handle tracking the branch's latest state.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# Reopen an existing branch by name from the table handle...
checked_out = table.branches.checkout("exp")
# ...or open it directly from the database connection.
branch_handle = db.open_table("quotes_branches_example", branch="exp")
print(checked_out.count_rows(), branch_handle.count_rows())  # both 4
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Reopen an existing branch by name from the table handle...
const checkedOut = await branches.checkout("exp");
// ...or open it directly from the database connection.
const branchHandle = await db.openTable(
  "quotes_branches_example",
  undefined,
  { branch: "exp" },
);
console.log(await checkedOut.countRows(), await branchHandle.countRows()); // both 4
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Reopen an existing branch by name from the table handle...
let checked_out = branches_table.checkout_branch("exp", None).await.unwrap();
// ...or open it directly via the connection's builder.
let opened = db
    .open_table("quotes_branches_example")
    .branch("exp")
    .execute()
    .await
    .unwrap();
println!(
    "Reopened rows: {}, {}",
    checked_out.count_rows(None).await.unwrap(),
    opened.count_rows(None).await.unwrap()
); // both 4
```

### Delete a branch

Deleting a branch removes it and its branch-local history; `main` is untouched.
A deployment refuses to delete a branch whose columns have been promoted onto
`main`, because `main` still depends on it.
Before deleting a branch, make sure you've retained any results you need. See
[Apply branch-tested changes to `main`](#apply-branch-tested-changes-to-main)
below.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# Delete the branch and its branch-local history. Data on main is safe.
table.branches.delete("exp")
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Delete the branch and its branch-local history. Data on main is safe.
await branches.delete("exp");
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Delete the branch and its branch-local history. Data on main is safe.
branches_table.delete_branch("exp").await.unwrap();
```

## Apply branch-tested changes to `main`

> [!WARNING]
>
> A branch has its own writable history. Outside of the [diff and cherry-pick
> APIs](#compare-and-merge-a-branch-into-main) (which are available on
> LanceDB Enterprise and promote added columns only), LanceDB does not reconcile
> one branch's history with another or detect conflicts between them. To carry
> other accepted work forward, rerun the validated operation against `main` or
> explicitly write selected results to it.

How you apply a validated change depends on the type of work:

* **Added columns (Enterprise):** review the branch with `diff`, then promote
  the new columns onto `main` with `cherry_pick` (`cherryPick` in TypeScript). See
  [Compare and promote a branch into `main`](#compare-and-merge-a-branch-into-main).
* **Backfill or transformation:** rerun the validated job against `main`.
* **Schema change:** apply the same reviewed schema operation to `main`.
* **Index change:** build the index on `main` using the configuration validated
  on the branch.
* **Selected row results:** upsert those rows into `main` using a stable unique
  key.

### Upsert selected branch rows into `main`

If the result you want to retain is a set of inserted or updated rows, use
[`merge_insert`](https://docs.lancedb.com/enterprise/v1-12-0/ingestion/merge-insert#merge-incoming-rows-by-key) to write them to
`main`. Despite its name, `merge_insert` is a row-ingestion operation: it
matches incoming rows by key and does not merge branch histories.

Read the rows you want from the reviewed branch, then upsert them into `main` on
your key column (`id` in this example). Here, `candidate` is the branch handle:

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# This is a row-level upsert, not a merge of branch histories.
# `merge_insert` updates matching rows and inserts new rows using a stable
# unique key. Filter the branch read if you only want to apply some results.
rows_to_apply = candidate.to_arrow()
(
    table.merge_insert("id")
    .when_matched_update_all()  # update rows that already exist on main
    .when_not_matched_insert_all()  # insert rows that are new on the branch
    .execute(rows_to_apply)
)
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// This is a row-level upsert, not a merge of branch histories.
// `mergeInsert` updates matching rows and inserts new rows using a stable
// unique key. Filter the branch read if you only want to apply some results.
const rowsToApply = await candidate.toArrow();
await table
  .mergeInsert("id")
  .whenMatchedUpdateAll() // update rows that already exist on main
  .whenNotMatchedInsertAll() // insert rows that are new on the branch
  .execute(rowsToApply);
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// This is a row-level upsert, not a merge of branch histories.
// `merge_insert` updates matching rows and inserts new rows using a stable
// unique key. Filter the branch read if you only want to apply some results.
let schema = candidate.schema().await.unwrap();
let batches = candidate
    .query()
    .execute()
    .await
    .unwrap()
    .try_collect::<Vec<_>>()
    .await
    .unwrap();
let rows_to_apply = RecordBatchIterator::new(batches.into_iter().map(Ok), schema);

let mut merge = branches_table.merge_insert(&["id"]);
merge
    .when_matched_update_all(None) // update rows that already exist on main
    .when_not_matched_insert_all(); // insert rows that are new on the branch
merge.execute(Box::new(rows_to_apply)).await.unwrap();
```

With LanceDB Enterprise, the synchronous Python table raises for `to_arrow()`; read
the branch's rows with a query instead. See
[Avoid materializing the whole table](https://docs.lancedb.com/enterprise/v1-12-0/search.md#avoid-materializing-the-whole-table).

This operation transfers only the inserted or updated rows in its input. It does
not transfer branch history, schema changes, indexes, or branch-local deletions,
and it does not determine which rows changed after the branch was created.

Reapplying an identical payload is idempotent on the key, but the operation is
not conflict-aware. If `main` has diverged, incoming branch rows can overwrite
newer values with the same key. Read and upsert the whole branch only when that
overwrite is intentional; otherwise, filter the branch read to the rows you
intend to apply.

## Compare and promote a branch into `main`

Enterprise

On LanceDB Enterprise, branches expose two review-and-land calls: `diff`
inspects what a branch has changed relative to `main`, and `cherry_pick`
(`cherryPick` in TypeScript) promotes the branch's new columns onto `main` in
place, without reissuing the branch's writes.

> [!NOTE]
>
> `diff` and `cherry_pick` work on LanceDB Enterprise tables only. On an Embedded
> table they fail as not supported: Python raises `NotImplementedError`, and
> TypeScript and Rust return an error. A cherry-pick promotes added columns; use
> the [upsert](#upsert-selected-branch-rows-into-main) or rerun patterns above for
> row and index changes.

### Diff a branch

`diff` reads the branch and `main` without modifying either, and returns what
has changed: columns added, removed or changed, indexes added or removed, row
counts, and a list of `errors` (the reasons a cherry-pick of the branch could
not land now). An empty list means it could.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
diff = table.branches.diff("exp")

print([c["name"] for c in diff["addedColumns"]])  # columns the branch introduced
print(diff["baseMoved"])        # True if main has moved on since the branch's fork
for error in diff["errors"]:    # empty when a cherry-pick could land
    print(error["code"], error["message"])
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
const branches = await table.branches();
const diff = await branches.diff("exp");

console.log(diff.addedColumns.map((c) => c.name)); // columns the branch introduced
console.log(diff.baseMoved);   // true if main has moved on since the branch's fork
for (const error of diff.errors) {  // empty when a cherry-pick could land
  console.log(error.code, error.message);
}
```

The result also carries the versions it compared (`parentVersion`,
`mainVersion`, `branchVersion`), `rowCountMain` and `rowCountBranch`, a
`rowSummary`, and `removedColumns`, `changedColumns`, `addedIndexes` and
`removedIndexes`. In Python the result is a dictionary with the same camelCase
keys.

The error codes are `baseMoved` (`main` has moved on since the version the
branch was forked from), `rowCountMismatch`, `rowsChanged`, `columnRemoved`,
`columnChanged`, `nothingToApply`, `noColumnChanges`, `inputColumnDependency`
and `parentNotMain`. A code the client does not know surfaces as `unknown`, so
older clients keep working.

### Promote a branch's columns

`cherry_pick` promotes the columns a branch added onto `main`. The server
re-evaluates the diff when the request arrives and either lands the change or
refuses it for the reasons `diff` would report. A refusal is not an exception:
the call returns a result whose `status` is `"failed"`, with the reasons in
`diff.errors`, so you can decide what to do next. Cherry-picks are not retried.

Pass `dry_run=True` in Python, or `true` as the second argument in TypeScript,
to check without landing anything. `preview.promotedColumns` lists the columns
the cherry-pick would promote, or did.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# Check first; this does not modify main.
preview = table.branches.cherry_pick("exp", dry_run=True)
print(preview["status"])                      # "ready" when it would land
print(preview["preview"]["promotedColumns"])

# Land it.
result = table.branches.cherry_pick("exp")
if result["status"] == "cherryPicked":
    print("landed at main version", result["mainVersionAfter"])
elif result["status"] == "failed":
    for error in result["diff"]["errors"]:
        print(error["code"], error["message"])
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
const branches = await table.branches();

// Check first; this does not modify main.
const preview = await branches.cherryPick("exp", true);
console.log(preview.status);                  // "ready" when it would land
console.log(preview.preview.promotedColumns);

// Land it.
const result = await branches.cherryPick("exp");
if (result.status === "cherryPicked") {
  console.log("landed at main version", result.mainVersionAfter);
} else if (result.status === "failed") {
  for (const error of result.diff.errors) {
    console.log(error.code, error.message);
  }
}
```

`status` is `ready` (a dry run that would land), `cherryPicked` (it landed, and
`mainVersionAfter` is the new version of `main`), `failed` (refused, or for a
dry run, would be refused; see `diff.errors`), `notImplemented`, or `unknown`
for a status the client does not know. A branch that does not exist raises a
not-found error instead of returning a status.

In async Python, await the same calls on an `AsyncTable`:
`await table.branches.diff("exp")` and
`await table.branches.cherry_pick("exp", dry_run=True)`. In Rust they are
`Table::diff_branch` and `Table::cherry_pick`.

## Build indexes on a branch

One of the most useful things a branch buys you is a safe place to build and
validate an index without affecting what's in production on the `main` branch.
Fork a branch, create your vector (ANN) and full-text search (FTS)
indexes on it, and check recall and latency. Once you have selected a
configuration, build the corresponding index on `main` through your normal
deployment workflow. Because the indexes live on the branch, queries against
`main` never see a half-built index and are never slowed down by the branch's
build.

This pattern is especially valuable on Enterprise deployments, where `main` is
typically serving production traffic while you tune an index configuration on
the side. A deployment builds the branch's indexes in the background, so wait
for them before measuring.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
# Build and validate indexes on a branch before using the configuration on
# main.
dev = products.branches.create("index-dev")

# A vector (ANN) index and a full-text search index, both branch-scoped.
dev.create_index(
    "vector",
    config=IvfPq(distance_type="cosine", num_partitions=1, num_sub_vectors=2),
)
dev.create_index("text", config=FTS())

# Both indexes live only on the branch; main still has none.
print([ix.name for ix in dev.list_indices()])  # branch: two indexes
print([ix.name for ix in products.list_indices()])  # main: [] (untouched)
```

```typescript TypeScript icon="square-js" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
// Build and validate indexes on a branch before using the configuration on
// main.
const dev = await productBranches.create("index-dev");

// A vector (ANN) index and a full-text search index, both branch-scoped.
await dev.createIndex("vector", {
  config: lancedb.Index.ivfPq({
    distanceType: "cosine",
    numPartitions: 1,
    numSubVectors: 2,
  }),
});
await dev.createIndex("text", { config: lancedb.Index.fts() });

// Both indexes live only on the branch; main still has none.
console.log((await dev.listIndices()).map((ix) => ix.name)); // branch: two indexes
console.log((await products.listIndices()).map((ix) => ix.name)); // main: [] (untouched)
```

```rust Rust icon="rust" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
use lancedb::index::scalar::FtsIndexBuilder;
use lancedb::index::Index;

// Build and validate indexes on a branch before using the configuration on
// main.
let dev = products
    .create_branch("index-dev", Ref::Version(None, None))
    .await
    .unwrap();

// A vector (ANN) index and a full-text search index, both branch-scoped.
dev.create_index(&["vector"], Index::Auto)
    .execute()
    .await
    .unwrap();
dev.create_index(&["text"], Index::FTS(FtsIndexBuilder::default()))
    .execute()
    .await
    .unwrap();

// Both indexes live only on the branch; main still has none.
println!("Branch indexes: {}", dev.list_indices().await.unwrap().len()); // 2
println!("Main indexes: {}", products.list_indices().await.unwrap().len()); // 0
```

Schema changes such as adding, altering, or dropping columns are branch-scoped in
the same way, so you can stage and review a larger reshaping of a table before
applying the same schema operations to `main`.

## Branches vs. tags vs. versions

Now that you're familiar with branches, you can see how they complement the other ways LanceDB
give you to work with table history. Choose these approaches based on whether you need to
*label*, *read*, or *write* data at a point in history:

| Feature | Writable? | Purpose |
| - | - | - |
| **[Branch](#work-with-branches)** | ✅ Yes | Write on top of a point in history without touching `main`. |
| **[Tag](https://docs.lancedb.com/enterprise/v1-12-0/management/table.md#versioning-tag-based-versioning)** | ❌ No | Attach a human-readable label to an existing version; protects it from cleanup. |
| **[`checkout(version)`](https://docs.lancedb.com/enterprise/v1-12-0/management/table#versioning-rollback-to-previous-versions)** | ❌ No | Read a historical version of `main` without forking. Read-only until you `restore`. |

> [!NOTE]
>
> For linear version history (creating versions, listing them, rolling back, and
> tagging), see the [Versioning and Reproducibility](https://docs.lancedb.com/enterprise/v1-12-0/management/table.md#versioning) guide.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.