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

# LanceDB

> Virtualize a LanceDB table from Node.

`LanceDBVFS` mounts a LanceDB table, read-only, as nested folders, one level per
group-by column. Each row is a Markdown card plus an optional blob file, such
as its image. Set up the local, object storage and LanceDB Cloud connections as in [LanceDB setup](https://docs.mirage.strukto.ai/home/setup/lancedb.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node @lancedb/lancedb
```

## Configure

```ts theme={null}
import { LanceDBVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const fashion = new LanceDBVFS({
  uri: '/data/fashion.lancedb',
  table: 'fashion',
  groupBy: ['gender', 'articleType', 'baseColour'],
  titleColumn: 'productDisplayName',
  blobColumn: 'image_bytes',
  blobExt: 'jpg',
  vectorColumn: 'vector',
})
const ws = new Workspace({ '/fashion': fashion }, { mode: MountMode.READ })

const result = await ws.shell('ls /fashion/Men/Shoes/White && cat /fashion/Men/Shoes/White/3.md')
console.log(result.stdoutText)
await ws.close()
```

`idColumn` (default `id`) names each row's files. Without `table`, every table
is a top-level folder.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**uri** `string` *required*

Database location: a local directory, an `s3://`, `gs://` or `az://` URI, or a `db://` URI for LanceDB Cloud or Enterprise.

**apiKey** `string` (default: null)

API key for LanceDB Cloud or Enterprise.

**region** `string` (default: 'us-east-1')

LanceDB Cloud region of a `db://` database; ignored for other URIs.

**hostOverride** `string` (default: null)

Endpoint of a LanceDB Enterprise deployment for a `db://` URI; ignored for other URIs.

**storageOptions** `object` (default: null)

Options passed to LanceDB's object-store layer, such as credentials or an endpoint for an `s3://` URI.

**table** `string` (default: null)

Table the mount root shows; unset lists every table as a top-level folder.

**groupBy** `string[]` (default: \[])

Columns that become folder levels, one per column in order; unset puts every row's files directly under the table.

**idColumn** `string` (default: 'id')

Column whose value names each row's files (`<id>.md`, `<id>.<blobExt>`).

**titleColumn** `string` (default: null)

Column whose value heads a row's card as a `# ` title; unset leaves the card without one.

**blobColumn** `string` (default: null)

Column of raw or base64 bytes served as `<id>.<blobExt>` and left out of the card; unset adds no blob file.

**blobExt** `string` (default: 'bin')

File extension of the blob file, without the dot.

**vectorColumn** `string` (default: null)

Embedding column left out of cards and listings.

**searchLimit** `number` (default: 10)

Results `search` returns when `--top-k` is not given.

**maxRows** `number` (default: 1000)

Most rows one folder listing reads; rows past it are left out, and a group folder lists only the values those rows carry.

Fields marked secret are redacted in snapshots.

## Authentication

A local directory needs no credentials. LanceDB Cloud takes its `db://` URI
with `apiKey` and `region` (default `us-east-1`); LanceDB Enterprise adds its
endpoint in `hostOverride`. An `s3://`, `gs://` or `az://` URI takes the
store's credentials or endpoint in `storageOptions`.

```ts theme={null}
const fashion = new LanceDBVFS({
  uri: process.env.LANCEDB_URI!,
  apiKey: process.env.LANCEDB_API_KEY!,
  region: process.env.LANCEDB_REGION!,
  table: 'fashion',
  groupBy: ['gender'],
})
```

## Layout

```text theme={null}
/fashion/
  Men/
    Shoes/
      White/
        3.jpg
        3.md
    Watches/
      Silver/
        15.jpg
        15.md
  Women/
    Tops/
      Blue/
        12.jpg
        12.md
```

Each folder level filters on one `groupBy` column, in order:
`/fashion/Men/Shoes/White/` lists the rows whose `gender` is `Men`,
`articleType` is `Shoes` and `baseColour` is `White`. Once every column is
bound, the folder lists each row's `<id>.md` and, with `blobColumn`, its
`<id>.<blobExt>`. A value holding `/` renders as `∕`, and a blank or dot-led
value is led by `⁄`, so every value keeps its own folder that lists and opens.

A card lists the row's columns, headed by `titleColumn`, without the vector and
blob columns.

## Behavior

* **Read-only:** no command changes the table.
* **Listing cap:** one folder listing reads at most `maxRows` (1,000) rows; rows
  past it are left out. Keep `groupBy` to low-cardinality columns on a large
  table.

### Semantic search

The `search` CLI runs LanceDB's vector search with
the table's embedding function, so the table needs one on a source column.
Register it on the workspace:

```ts theme={null}
import { SEARCH } from '@struktoai/mirage-node'

ws.registerCli('search', SEARCH)
```

Each hit prints its card's path with the vector distance, then the card, so
results work with `cat`, pipes and `wc`:

```text theme={null}
$ search "white running sneakers" /fashion
/fashion/Men/Shoes/White/3.md:0.2679
# Nike Men White Running Sneakers
...
```

`--top-k` defaults to `searchLimit` (10). `--threshold` is the largest distance
kept. `--method` takes only `semantic`.

## Integration

LanceDB answers this command through its own API, so fewer cards are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -r` and `rg`: a `LIKE` query over each row's string columns picks the
  cards to read, for any text, and misses nothing. A text that could match a
  column's name, a boolean or `null`, or the `column: ` prefix reads every
  card, as does a table that renders a list, struct or bytes column.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with LanceDB mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `lancedb`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> * Directories are the configured group-by columns; descending one narrows
>   a filter.
> * Each matching row is a `<id>.md` card plus a `<id>.<ext>` blob file.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `lancedb` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `lancedb` answers only for `*/*.md`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `lancedb`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> - Directories are the configured group-by columns; descending one narrows
>   a filter.
> - Each matching row is a `<id>.md` card plus a `<id>.<ext>` blob file.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `lancedb` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `lancedb` answers only for `*/*.md`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


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