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

---
title: LanceDB
icon: database
description: Set up the LanceDB resource in Python, including LanceDB OSS, object storage, LanceDB Cloud, and LanceDB Enterprise, with semantic search.
---

The LanceDB resource mounts a LanceDB table as a filesystem: group-by columns
become folders, rows become files, and semantic search is the `search` command.
See [LanceDB Resource](/python/resource/lancedb) for the full layout and command
list.

## Dependencies

```bash
uv add lancedb
```

`lancedb` ships the embedded engine and the async client Mirage uses. It pulls
in `pyarrow`; no separate server is required.

Semantic search needs an embedding function inside the table. For real
multimodal (CLIP) embeddings, add the model deps to your **builder**
environment only (Mirage core never imports them):

```bash
uv add open-clip-torch torch
```

## Where the data lives

A LanceDB database is a directory of Lance files. The `uri` decides where it is
stored, and the same `LanceDBConfig` works for every tier.

### LanceDB OSS (local disk)

```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",
)
ws = Workspace({"/fashion/": LanceDBResource(config)}, mode=MountMode.READ)
```

### Object storage (S3 / GCS / Azure)

Point `uri` at a bucket. Credentials come from the environment by default, or
pass them through `storage_options`.

```python
config = LanceDBConfig(
    uri="s3://my-bucket/fashion.lancedb",
    table="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_column="id",
    vector_column="vector",
    storage_options={"region": "us-east-1"},
)
```

### LanceDB Cloud

Use a `db://` URI plus an API key and region. The API key can also come from the
`LANCEDB_API_KEY` environment variable.

```python
import os

config = LanceDBConfig(
    uri="db://my-database",
    api_key=os.environ["LANCEDB_API_KEY"],
    region="us-east-1",
    table="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_column="id",
    vector_column="vector",
)
ws = Workspace({"/fashion/": LanceDBResource(config)}, mode=MountMode.READ)
```

### LanceDB Enterprise

Enterprise is the same as Cloud plus a custom endpoint via `host_override`.

```python
config = LanceDBConfig(
    uri="db://my-database",
    api_key=os.environ["LANCEDB_API_KEY"],
    host_override="https://my-database.us-east-1.api.lancedb.com",
    region="us-east-1",
    table="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_column="id",
    vector_column="vector",
)
```

`region` and `host_override` are only applied for `db://` URIs; they are ignored
for local and object-storage mounts.

## Search setup

Search is powered by the table's own embedding function, not by Mirage. The
`search` command is available when `vector_column` is set; the table must have
been created with an embedding function registered on a source field.

A minimal CLIP-backed table (run once in your builder environment):

```python
import lancedb
from lancedb.embeddings import get_registry
from lancedb.pydantic import LanceModel, Vector

func = get_registry().get("open-clip").create()

class Product(LanceModel):
    id: int
    gender: str
    articleType: str
    baseColour: str
    productDisplayName: str = func.SourceField()  # text the model embeds
    image_bytes: bytes
    vector: Vector(func.ndims()) = func.VectorField()

db = lancedb.connect("/data/fashion.lancedb")
table = db.create_table("fashion", schema=Product)
table.add(rows)  # rows include image_bytes
```

Once mounted, querying is the `search` command. LanceDB embeds the query text
with the same model and runs vector search, returning ranked rows as canonical
file paths with a score, then their cards:

```bash
search "red running shoes" /fashion          # ranked <path>.md:score + card body
cat /fashion/Men/Shoes/White/3.md             # follow a result to the real file
```

A runnable, dependency-free version (a lightweight keyword embedding instead of
CLIP) lives in `examples/python/lancedb/`.

## Config reference

| Field            | Required | Default       | Description                                                        |
| ---------------- | -------- | ------------- | ------------------------------------------------------------------ |
| `uri`            | Yes      |               | Local path, `s3://`/`gs://`/`az://`/`hf://`, or `db://` (Cloud)    |
| `api_key`        | No       |               | LanceDB Cloud/Enterprise API key (or `LANCEDB_API_KEY`)            |
| `region`         | No       | `us-east-1`   | Cloud region (`db://` only)                                        |
| `host_override`  | No       |               | Enterprise endpoint URL (`db://` only)                             |
| `storage_options`| No       |               | Object-storage options/credentials                                |
| `table`          | No       |               | Pin one table; the mount root becomes that table                  |
| `group_by`       | No       | `[]`          | Columns that become nested folder levels                          |
| `id_column`      | No       | `id`          | Column used to name row files                                     |
| `title_column`   | No       |               | Column used as the card heading                                   |
| `blob_column`    | No       |               | Column served as the raw blob/image file                         |
| `blob_ext`       | No       | `bin`         | Extension for the blob file (`jpg`, `png`, ...)                   |
| `vector_column`  | No       |               | Vector column; presence enables the `search` command            |
| `search_limit`   | No       | `10`          | Default top-k returned by `search`                              |
| `max_rows`       | No       | `1000`        | Cap on rows scanned per folder listing                           |

The mount is read-only. See [LanceDB Resource](/python/resource/lancedb) for the
filesystem layout and supported commands.