LanceDB

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 for the full layout and command list.

Dependencies

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):

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)

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.

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.

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.

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):

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:

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 for the filesystem layout and supported commands.

Getting Started

Agents

Resources

Watch

Runtimes

Dependencies

Where the data lives

LanceDB OSS (local disk)

Object storage (S3 / GCS / Azure)

LanceDB Cloud

LanceDB Enterprise

Search setup

Config reference

​Dependencies

​Where the data lives

​LanceDB OSS (local disk)

​Object storage (S3 / GCS / Azure)

​LanceDB Cloud

​LanceDB Enterprise

​Search setup

​Config reference

Dependencies

Where the data lives

LanceDB OSS (local disk)

Object storage (S3 / GCS / Azure)

LanceDB Cloud

LanceDB Enterprise

Search setup

Config reference