strukto-ai--mirage/docs/python/resource/lancedb.mdx

---
title: LanceDB
description: Mount a LanceDB table as a Mirage filesystem, with label folders, multimodal blobs, and a semantic search command for Python agents.
icon: database
---

The LanceDB resource 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` command, which returns ranked rows as canonical file paths.

For connection setup (LanceDB OSS, object storage, Cloud, Enterprise), see
[LanceDB Setup](/python/setup/lancedb).

## Config

```python
from mirage import MountMode, Workspace
from mirage.resource.lancedb import LanceDBConfig, LanceDBResource

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,
)
resource = LanceDBResource(config)
ws = Workspace({"/fashion/": resource}, 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. See the full
[config reference](/python/setup/lancedb#config-reference).

## Filesystem layout

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

```text
/                                  # 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
```

When `table` is set the table level is elided, so the mount root is that table:

```text
/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.

```text
# 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 a command, not a path. 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`:

```text
$ 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).

## 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                        |
| `search`      | semantic (vector) search -> ranked canonical paths + score    |
| `head` / `tail` | first/last lines of a card                                  |
| `wc`          | count lines/bytes of a card                                   |

`grep`/`rg` stay lexical (literal/regex). `search` 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.

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