LanceDB

The LanceDB VFS exposes a LanceDB table as a virtual filesystem mounted at some prefix such as /fashion/. Group-by columns become nested folders, each row becomes a card plus an optional blob file, and semantic search is the search CLI, which returns ranked rows as canonical file paths. For connection setup (LanceDB OSS, object storage, Cloud, Enterprise), see LanceDB Setup. Install the extra:

pip install "mirage-ai[lancedb]"

Config

from mirage import MountMode, Workspace
from mirage.vfs.lancedb import LanceDBConfig, LanceDBVFS

config = LanceDBConfig(
    uri="/data/fashion.lancedb",
    table="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_column="id",
    title_column="productDisplayName",
    blob_column="image_bytes",
    blob_ext="jpg",
    vector_column="vector",
    search_limit=5,
)
vfs = LanceDBVFS(config)
ws = Workspace({"/fashion/": vfs}, mode=MountMode.READ)

The mapping is config-driven; nothing about the dataset is hardcoded. Point group_by at different columns and the folder tree changes.

Field	Description
`timeout` default `30`	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` required	Database location: a local directory, an `s3://`, `gs://` or `az://` URI, or a `db://` URI for LanceDB Cloud or Enterprise.
`api_key` secret	API key for LanceDB Cloud or Enterprise.
`region` default `'us-east-1'`	LanceDB Cloud region of a `db://` database; ignored for other URIs.
`host_override`	Endpoint of a LanceDB Enterprise deployment for a `db://` URI; ignored for other URIs.
`storage_options`	Options passed to LanceDB’s object-store layer, such as credentials or an endpoint for an `s3://` URI.
`table`	Table the mount root shows; unset lists every table as a top-level folder.
`group_by` default `[]`	Columns that become folder levels, one per column in order; unset puts every row’s files directly under the table.
`id_column` default `'id'`	Column whose value names each row’s files (`<id>.md`, `<id>.<blob_ext>`).
`title_column`	Column whose value heads a row’s card as a `#` title; unset leaves the card without one.
`blob_column`	Column of raw or base64 bytes served as `<id>.<blob_ext>` and left out of the card; unset adds no blob file.
`blob_ext` default `'bin'`	File extension of the blob file, without the dot.
`vector_column`	Embedding column left out of cards and listings.
`search_limit` default `10`	Results `search` returns when `--top-k` is not given.
`max_rows` 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.

VFS.md

The VFS.md an agent reads with LanceDB mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`lancedb`, read

`/<path>` layout

This mount is a LanceDB table exposed as a filesystem.

Directories are the configured group-by columns; descending narrows a filter.
Each matching row is a <id>.md card plus a <id>.<ext> blob file. Use
ls/cd/cat/tree/find/wc/grep/rg as usual.

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.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `lancedb`, read |

## `/<path>` layout

```text
This mount is a LanceDB table exposed as a filesystem.

Directories are the configured group-by columns; descending narrows a filter.
Each matching row is a <id>.md card plus a <id>.<ext> blob file. Use
ls/cd/cat/tree/find/wc/grep/rg as usual.
```

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

Every path is translated into a LanceDB query. Descending a folder adds one WHERE clause; the leaf level lists rows.

/                                  # list tables (omitted when `table` is pinned)
/<table>/                          # distinct group_by[0] values
  <v1>/                            # distinct group_by[1] WHERE group_by[0]=v1
    .../<vN>/                      # all group-by columns bound -> row files
      <id>.md                      # rendered card (text)
      <id>.<ext>                   # raw blob / image bytes

A group value holding / renders as ∕, and a blank or dot-led value is led by ⁄, so every value keeps its own directory that lists and opens, and descending into it filters for exactly that value. When table is set the table level is elided, so the mount root is that table:

/fashion/
  Men/
    Shoes/
      White/
        3.md
        3.jpg

Row cards

A <id>.md card renders the row’s columns as readable text and points at its blob. The vector and blob columns are omitted from the card body.

# Nike Men White Running Sneakers

id: 3
gender: Men
articleType: Shoes
baseColour: White
productDisplayName: Nike Men White Running Sneakers
blob: 3.jpg

Semantic search

Search is the search CLI, not a path. Register it on the workspace:

from mirage.commands.cli.builtin.search import SEARCH

ws.register_cli("search", SEARCH)

It returns each ranked row as its canonical file path (the same <id>.md you would cat while browsing) annotated with the vector distance, followed by the card body. Results point back at the real files, so search composes with cat, pipes, and wc:

$ search "white running sneakers" /fashion
/fashion/Men/Shoes/White/3.md:0.2679
# Nike Men White Running Sneakers

id: 3
gender: Men
articleType: Shoes
baseColour: White
productDisplayName: Nike Men White Running Sneakers
blob: 3.jpg
...

Flags: --top-k <n> (default search_limit), --threshold <max-distance>, --method semantic (the only supported method; grep/rg stay lexical).

Integration

What LanceDB answers through its own API, so fewer files are read. Integration explains each command.

Command	On LanceDB
`grep -r`, `rg`	The string columns of each row, for any text; a table with list, struct or bytes columns reads every card. It misses nothing.

Supported commands

All commands delegate to Mirage’s shared implementations.

Command	Behaviour on a LanceDB mount
`ls`	list tables, label folders, or row files
`cd`	navigate (each level narrows the filter)
`tree`	render the label hierarchy
`cat`	print a row card, or dump raw blob/image bytes
`stat`	directory vs file, blob size, image mime type
`find`	walk the tree (e.g. `find /fashion -name '*.md'`)
`grep` / `rg`	lexical search over the rendered cards
`head` / `tail`	first/last lines of a card
`wc`	count lines/bytes of a card

grep/rg stay lexical (literal/regex). The search CLI is the semantic path: it auto-embeds the query via the table’s embedding function and returns ranked rows as canonical file paths, which compose with cat, wc, and pipes. grep -r and rg read only the cards whose string columns hold the text, which a LIKE query answers. 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.

Access pattern

The mount is read-only (MountMode.READ); writes are not supported. The two read modes are:

Browse by label folders: pure metadata WHERE filters, no embedding.
Search by meaning: the search CLI’s search "<query>" <path> runs vector search using the table’s embedding function and returns canonical row paths.

Folder listings scan one column with SELECT DISTINCT and are capped by max_rows, so very large tables should keep group_by to low-cardinality columns.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Row cards

Semantic search

Integration

Supported commands

Access pattern

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Row cards

​Semantic search

​Integration

​Supported commands

​Access pattern

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Row cards

Semantic search

Integration

Supported commands

Access pattern