docs: document table branches

Author: mintlify[bot]

docs/docs.json

@@ -75,6 +75,7 @@
                   "tables/schema",
                   "tables/update",
                   "tables/versioning",
+                  "tables/branches",
                   "tables/consistency"
                 ]
               },

docs/snippets/tables.mdx

@@ -28,6 +28,8 @@ export const PyAlterVectorColumn = "vector_dim = 768  # Your embedding dimension
 
 export const PyBatchDataInsertion = "import pyarrow as pa\n\ndef make_batches():\n    for i in range(5):  # Create 5 batches\n        yield pa.RecordBatch.from_arrays(\n            [\n                pa.array([[3.1, 4.1], [5.9, 26.5]], pa.list_(pa.float32(), 2)),\n                pa.array([f\"item{i * 2 + 1}\", f\"item{i * 2 + 2}\"]),\n                pa.array([float((i * 2 + 1) * 10), float((i * 2 + 2) * 10)]),\n            ],\n            [\"vector\", \"item\", \"price\"],\n        )\n\nschema = pa.schema(\n    [\n        pa.field(\"vector\", pa.list_(pa.float32(), 2)),\n        pa.field(\"item\", pa.utf8()),\n        pa.field(\"price\", pa.float32()),\n    ]\n)\n# Create table with batches\ntable_name = \"batch_ingestion_example\"\ntable = db.create_table(table_name, make_batches(), schema=schema, mode=\"overwrite\")\n";
 
+export const PyBranches = "# Fork an isolated, writable branch from main.\n# The returned handle is scoped to the branch; writes on it do not\n# affect main.\nbranch = table.branches.create(\"exp\")\nbranch.add([{\"vector\": [10.0, 11.0], \"item\": \"baz\", \"price\": 30.0}])\nprint(branch.count_rows())  # 3 rows on the branch\nprint(table.count_rows())   # main is still untouched\n\n# List all branches on the table.\nprint(table.branches.list())\n\n# Reopen the branch later by name.\ncheckedOut = table.branches.checkout(\"exp\")\n\n# Or open a branch directly from the database connection.\nbranch_handle = db.open_table(\"quotes_versioning_example\", branch=\"exp\")\n\n# Delete a branch when you're done with it.\ntable.branches.delete(\"exp\")\n";
+
 export const PyConsistencyCheckoutLatest = "uri = str(tmp_db.uri)\nwriter_db = lancedb.connect(uri)\nreader_db = lancedb.connect(uri)\nwriter_table = writer_db.create_table(\n    \"consistency_checkout_latest_table\", [{\"id\": 1}], mode=\"overwrite\"\n)\nreader_table = reader_db.open_table(\"consistency_checkout_latest_table\")\n\nwriter_table.add([{\"id\": 2}])\nrows_before_refresh = reader_table.count_rows()\nprint(f\"Rows before checkout_latest: {rows_before_refresh}\")\n\nreader_table.checkout_latest()\nrows_after_refresh = reader_table.count_rows()\nprint(f\"Rows after checkout_latest: {rows_after_refresh}\")\n";
 
 export const PyConsistencyEventual = "from datetime import timedelta\n\nuri = str(tmp_db.uri)\nwriter_db = lancedb.connect(uri)\nreader_db = lancedb.connect(uri, read_consistency_interval=timedelta(seconds=3600))\nwriter_table = writer_db.create_table(\n    \"consistency_eventual_table\", [{\"id\": 1}], mode=\"overwrite\"\n)\nreader_table = reader_db.open_table(\"consistency_eventual_table\")\nwriter_table.add([{\"id\": 2}])\nrows_after_write = reader_table.count_rows()\nprint(f\"Rows visible before eventual refresh interval: {rows_after_write}\")\n";
@@ -140,6 +142,8 @@ export const TsAlterColumnsWithExpression = "// For custom transforms, create a
 
 export const TsAlterVectorColumn = "const oldDim = 384;\nconst newDim = 1024;\nconst vectorSchema = new arrow.Schema([\n  new arrow.Field(\"id\", new arrow.Int64()),\n  new arrow.Field(\n    \"embedding\",\n    new arrow.FixedSizeList(\n      oldDim,\n      new arrow.Field(\"item\", new arrow.Float16(), true),\n    ),\n    true,\n  ),\n]);\nconst vectorData = lancedb.makeArrowTable(\n  [{ id: 1, embedding: Array.from({ length: oldDim }, () => Math.random()) }],\n  { schema: vectorSchema },\n);\nconst vectorTable = await db.createTable(\"vector_alter_example\", vectorData, {\n  mode: \"overwrite\",\n});\n\n// Changing FixedSizeList dimensions (384 -> 1024) is not supported via alterColumns.\n// Use addColumns + dropColumns + alterColumns(rename) to replace the column.\nawait vectorTable.addColumns([\n  {\n    name: \"embedding_v2\",\n    valueSql: `arrow_cast(NULL, 'FixedSizeList(${newDim}, Float16)')`,\n  },\n]);\nawait vectorTable.dropColumns([\"embedding\"]);\nawait vectorTable.alterColumns([{ path: \"embedding_v2\", rename: \"embedding\" }]);\n";
 
+export const TsBranches = "const branches = await table.branches();\n\n// Fork an isolated, writable branch from main.\n// The returned handle is scoped to the branch; writes on it do not\n// affect main.\nconst branch = await branches.create(\"exp\");\nawait branch.add([{ id: 2, author: \"Morty\", quote: \"Aww geez, Rick!\" }]);\n\n// List all branches on the table.\nconsole.log(await branches.list());\n\n// Reopen the branch later by name.\nconst checkedOut = await branches.checkout(\"exp\");\n\n// Or open a branch directly from the database connection.\nconst branchHandle = await db.openTable(\n  \"quotes_versioning_example\",\n  undefined,\n  { branch: \"exp\" },\n);\n\n// Delete a branch when you're done with it.\nawait branches.delete(\"exp\");\n";
+
 export const TsConsistencyCheckoutLatest = "const checkoutWriterDb = await lancedb.connect(databaseDir);\nconst checkoutReaderDb = await lancedb.connect(databaseDir);\nconst checkoutWriterTable = await checkoutWriterDb.createTable(\n  \"consistency_checkout_latest_table\",\n  [{ id: 1 }],\n  { mode: \"overwrite\" },\n);\nconst checkoutReaderTable = await checkoutReaderDb.openTable(\n  \"consistency_checkout_latest_table\",\n);\nawait checkoutWriterTable.add([{ id: 2 }]);\nconst rowsBeforeRefresh = await checkoutReaderTable.countRows();\nconsole.log(`Rows before checkoutLatest: ${rowsBeforeRefresh}`);\nawait checkoutReaderTable.checkoutLatest();\nconst rowsAfterRefresh = await checkoutReaderTable.countRows();\nconsole.log(`Rows after checkoutLatest: ${rowsAfterRefresh}`);\n";
 
 export const TsConsistencyEventual = "const eventualWriterDb = await lancedb.connect(databaseDir);\nconst eventualReaderDb = await lancedb.connect(databaseDir, {\n  readConsistencyInterval: 3600,\n});\nconst eventualWriterTable = await eventualWriterDb.createTable(\n  \"consistency_eventual_table\",\n  [{ id: 1 }],\n  { mode: \"overwrite\" },\n);\nconst eventualReaderTable = await eventualReaderDb.openTable(\n  \"consistency_eventual_table\",\n);\nawait eventualWriterTable.add([{ id: 2 }]);\nconst eventualRowsAfterWrite = await eventualReaderTable.countRows();\nconsole.log(\n  `Rows visible before eventual refresh interval: ${eventualRowsAfterWrite}`,\n);\n";
@@ -234,6 +238,8 @@ export const RsAlterColumnsWithExpression = "// For custom transforms, create a
 
 export const RsAlterVectorColumn = "let old_dim = 384;\nlet new_dim = 1024;\nlet vector_schema = Arc::new(Schema::new(vec![\n    Field::new(\"id\", DataType::Int64, false),\n    Field::new(\n        \"embedding\",\n        DataType::FixedSizeList(\n            Arc::new(Field::new(\"item\", DataType::Float32, true)),\n            old_dim,\n        ),\n        true,\n    ),\n]));\nlet vector_batch = RecordBatch::try_new(\n    vector_schema.clone(),\n    vec![\n        Arc::new(Int64Array::from(vec![1])),\n        Arc::new(\n            FixedSizeListArray::from_iter_primitive::<Float32Type, _, _>(\n                vec![Some(vec![Some(0.1_f32); old_dim as usize])],\n                old_dim,\n            ),\n        ),\n    ],\n)\n.unwrap();\nlet vector_reader: Box<dyn RecordBatchReader + Send> =\n    Box::new(RecordBatchIterator::new(vec![Ok(vector_batch)].into_iter(), vector_schema.clone()));\nlet vector_table = db\n    .create_table(\"vector_alter_example\", vector_reader)\n    .mode(CreateTableMode::Overwrite)\n    .execute()\n    .await\n    .unwrap();\n\n// Changing FixedSizeList dimensions (384 -> 1024) is not supported via alter_columns.\n// Use add_columns + drop_columns + alter_columns(rename) to replace the column.\nvector_table\n    .add_columns(\n        NewColumnTransform::SqlExpressions(vec![(\n            \"embedding_v2\".to_string(),\n            format!(\"arrow_cast(NULL, 'FixedSizeList({}, Float32)')\", new_dim),\n        )]),\n        None,\n    )\n    .await\n    .unwrap();\nvector_table.drop_columns(&[\"embedding\"]).await.unwrap();\nvector_table\n    .alter_columns(&[ColumnAlteration::new(\"embedding_v2\".to_string())\n        .rename(\"embedding\".to_string())])\n    .await\n    .unwrap();\n";
 
+export const RsBranches = "use lance::dataset::refs::Ref;\n\n// Fork an isolated, writable branch from main's latest version.\n// The returned handle is scoped to the branch; writes on it do not\n// affect main.\nlet branch = table\n    .create_branch(\"exp\", Ref::Version(None, None))\n    .await\n    .unwrap();\nbranch.add(make_quotes_reader(vec![(4, \"Morty\", \"Aww geez, Rick!\")]))\n    .execute()\n    .await\n    .unwrap();\n\n// List all branches on the table.\nlet branches = table.list_branches().await.unwrap();\nprintln!(\"Branches: {:?}\", branches);\n\n// Reopen the branch later by name, or open it directly via the builder.\nlet _checked_out = table.checkout_branch(\"exp\").await.unwrap();\nlet _opened = db\n    .open_table(\"quotes_versioning_example\")\n    .branch(\"exp\")\n    .execute()\n    .await\n    .unwrap();\n\n// Delete a branch when you're done with it.\ntable.delete_branch(\"exp\").await.unwrap();\n";
+
 export const RsConsistencyCheckoutLatest = "let checkout_writer_db = connect(&db_uri).execute().await.unwrap();\nlet checkout_reader_db = connect(&db_uri).execute().await.unwrap();\nlet checkout_writer_table = checkout_writer_db\n    .create_table(\n        \"consistency_checkout_latest_table\",\n        make_users_reader(vec![1], vec![\"Alice\"], None),\n    )\n    .mode(CreateTableMode::Overwrite)\n    .execute()\n    .await\n    .unwrap();\nlet checkout_reader_table = checkout_reader_db\n    .open_table(\"consistency_checkout_latest_table\")\n    .execute()\n    .await\n    .unwrap();\ncheckout_writer_table\n    .add(make_users_reader(vec![2], vec![\"Bob\"], None))\n    .execute()\n    .await\n    .unwrap();\nlet rows_before_refresh = checkout_reader_table.count_rows(None).await.unwrap();\nprintln!(\"Rows before checkout_latest: {}\", rows_before_refresh);\ncheckout_reader_table.checkout_latest().await.unwrap();\nlet rows_after_refresh = checkout_reader_table.count_rows(None).await.unwrap();\nprintln!(\"Rows after checkout_latest: {}\", rows_after_refresh);\n";
 
 export const RsConsistencyEventual = "let eventual_writer_db = connect(&db_uri).execute().await.unwrap();\nlet eventual_reader_db = connect(&db_uri)\n    .read_consistency_interval(StdDuration::from_secs(3600))\n    .execute()\n    .await\n    .unwrap();\nlet eventual_writer_table = eventual_writer_db\n    .create_table(\n        \"consistency_eventual_table\",\n        make_users_reader(vec![1], vec![\"Alice\"], None),\n    )\n    .mode(CreateTableMode::Overwrite)\n    .execute()\n    .await\n    .unwrap();\nlet eventual_reader_table = eventual_reader_db\n    .open_table(\"consistency_eventual_table\")\n    .execute()\n    .await\n    .unwrap();\neventual_writer_table\n    .add(make_users_reader(vec![2], vec![\"Bob\"], None))\n    .execute()\n    .await\n    .unwrap();\nlet eventual_rows_after_write = eventual_reader_table.count_rows(None).await.unwrap();\nprintln!(\n    \"Rows visible before eventual refresh interval: {}\",\n    eventual_rows_after_write\n);\n";

docs/tables/branches.mdx

@@ -0,0 +1,97 @@
+---
+title: "Table branches"
+sidebarTitle: "Branches"
+description: "Fork isolated, writable copies of a LanceDB table to test changes without touching main."
+icon: "code-branch"
+keywords: ["branches", "branch", "versioning", "fork", "isolation"]
+---
+import {
+    PyBranches as Branches,
+    TsBranches as TsBranches,
+    RsBranches as RsBranches,
+} from '/snippets/tables.mdx';
+
+Branches are isolated, writable lines of history forked from another branch
+(or a specific version). Writes on a branch do not affect `main`, and you can
+list, check out, or delete branches at any time. Branches are similar in spirit
+to git branches but operate at the table level.
+
+Use branches 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.
+
+<Note>
+Branches are supported on local and embedded LanceDB tables. Remote tables
+served by LanceDB Enterprise do not yet support branches.
+</Note>
+
+## Create, write, and check out a branch
+
+Forking a branch returns a new table handle scoped to that branch. All reads
+and writes through the handle stay on the branch — `main` is untouched until
+you explicitly promote the data yourself (for example, by copying rows back).
+
+`branches.create(name)` forks from `main`'s latest version by default. To fork
+from a different source, pass `from_ref` (a branch name) and/or `from_version`
+(a specific version on that ref).
+
+<CodeGroup>
+    <CodeBlock filename="Python" language="Python" icon="python">
+    {Branches}
+    </CodeBlock>
+
+    <CodeBlock filename="TypeScript" language="TypeScript" icon="square-js">
+    {TsBranches}
+    </CodeBlock>
+
+    <CodeBlock filename="Rust" language="Rust" icon="rust">
+    {RsBranches}
+    </CodeBlock>
+</CodeGroup>
+
+`branches.list()` returns a map of branch name to metadata, including the
+parent branch (`None`/`null` for branches forked from `main`).
+
+## Open a branch directly
+
+If you already know the branch you want, you can skip the explicit checkout
+and pass the branch name to `open_table` / `openTable`. The returned table
+handle behaves the same as one returned by `branches.checkout()`.
+
+<CodeGroup>
+```python Python icon="python"
+# Reads and writes operate in the branch's context
+branch = db.open_table("items", branch="exp")
+```
+
+```typescript TypeScript icon="square-js"
+// Reads and writes operate in the branch's context
+const branch = await db.openTable("items", undefined, { branch: "exp" });
+```
+
+```rust Rust icon="rust"
+// Reads and writes operate in the branch's context
+let branch = db
+    .open_table("items")
+    .branch("exp")
+    .execute()
+    .await?;
+```
+</CodeGroup>
+
+## Branches versus tags
+
+Branches and [tags](/tables/versioning#tag-based-versioning) 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 — 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"`) |
+
+Reach for a branch when you need to write data; reach for a tag when you just
+need a stable label on an existing version.