mirror of https://github.com/lancedb/lancedb.git synced 2026-07-03 11:00:40 +00:00

Files

Brendan Clement d9018067b3 feat: support checking out a version on a branch (#3504 )

### 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.

2026-06-08 17:36:38 -07:00

1.6 KiB

Raw Blame History

@lancedb/lancedb • Docs

@lancedb/lancedb / OpenTableOptions

Interface: OpenTableOptions

Properties

branch?

optional branch: string;

Open the table scoped to this branch instead of the default branch.

Reads and writes on the returned table operate in the branch's context.

indexCacheSize?

optional indexCacheSize: number;

Set the size of the index cache, specified as a number of entries

Deprecated

Use session-level cache configuration instead. Create a Session with custom cache sizes and pass it to the connect() function.

The exact meaning of an "entry" will depend on the type of index:

IVF: there is one entry for each IVF partition
BTREE: there is one entry for the entire index

This cache applies to the entire opened table, across all indices. Setting this value higher will increase performance on larger datasets at the expense of more RAM

storageOptions?

optional storageOptions: Record<string, string>;

Configuration for object storage.

Options already set on the connection will be inherited by the table, but can be overridden here.

The available options are described at https://docs.lancedb.com/storage/

version?

optional version: number;

Open the table pinned to this version, producing a read-only view.

Composes with OpenTableOptions.branch: when both are set, opens that branch at the version; otherwise opens main at the version. Call checkoutLatest to return to a writable state.

1.6 KiB Raw Blame History