main, and you
can list, check out, or delete branches at any time. They are similar in spirit
to git branches, but operate at the table level.
Use a branch when you want to:
- Try a destructive operation (re-embed, schema change, bulk update) without risking the production table.
- Stage data for evaluation, then promote or discard it.
- Run experiments in parallel against the same base data.
Branches are available for local and embedded LanceDB tables. Remote tables
(LanceDB Enterprise) do not support branches yet.
Create, write, and check out a branch
Forking a branch returns a new table handle scoped to that branch. All reads and writes through that handle stay on the branch, leavingmain untouched until
you explicitly promote the data yourself (for example, by copying rows back).
There is no automatic merge.
branches.create(name) forks from main’s latest version by default. To fork
from somewhere else, pass a branch name, a specific version, or both.
branches.list() returns a map of branch name to metadata, including which
branch each was forked from. main is the reserved default branch: wherever a
branch is optional, leaving it out means main. To skip the explicit
checkout, open a branch straight from the connection with
open_table(..., branch=...) (openTable(..., { branch }) in TypeScript, or
the .branch(...) builder in Rust), as shown at the end of each example above.
Branches versus Tags
Branches and Tags both attach human-readable names to a table’s history, but they serve different goals:| Branches | Tags | |
|---|---|---|
| Writable | Yes, each branch has its own history | No, just a label on an immutable version |
Affects main on write | No | N/A (Tags can’t be written to) |
| Typical use | Experiments, staging, isolation | Pinning a known-good version ("prod", "baseline") |