LanceDB

LanceDBVFS exposes a LanceDB table as a read-only filesystem: group-by columns become nested folders, each row is a card plus an optional blob file, and semantic search is the search command. The TypeScript backend mirrors the Python one and returns identical results.

Node

pnpm add @struktoai/mirage-node @lancedb/lancedb

import { LanceDBVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const fashion = new LanceDBVFS({
  config: {
    uri: '/data/fashion.lancedb', // or s3://, gs://, db:// (LanceDB Cloud)
    table: 'fashion',
    groupBy: ['gender', 'articleType', 'baseColour'],
    idColumn: 'id',
    titleColumn: 'productDisplayName',
    blobColumn: 'image_bytes',
    blobExt: 'jpg',
    vectorColumn: 'vector', // presence enables the search command
    searchLimit: 5,
  },
})

const ws = new Workspace({ '/fashion/': fashion }, { mode: MountMode.READ })

await ws.execute('ls /fashion/Men/Shoes/White')
await ws.execute('search "red running shoes" /fashion') // ranked paths + score + card

Filesystem layout

/fashion/<gender>/<articleType>/<baseColour>/<id>.md   # row card
/fashion/<gender>/<articleType>/<baseColour>/<id>.jpg  # raw blob bytes

A groupBy 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. Semantic search is the search command, not a path: it returns ranked rows as the canonical <id>.md paths above, annotated with the vector distance.

Cloud and Enterprise

db:// URIs connect to LanceDB Cloud (apiKey + region) or Enterprise (apiKey + hostOverride):

const fashion = new LanceDBVFS({
  config: {
    uri: 'db://my-database',
    apiKey: process.env.LANCEDB_API_KEY,
    region: 'us-east-1',
    hostOverride: 'https://my-database.us-east-1.api.lancedb.com', // Enterprise only
    table: 'fashion',
    groupBy: ['gender'],
    idColumn: 'id',
    vectorColumn: 'vector',
  },
})

Supported commands

ls, cd, tree, cat, stat, find, wc, and search. grep/rg stay lexical; search "<query>" <path> is the semantic command, returning ranked rows as canonical <id>.md paths plus a score, so results compose with cat, wc, and pipes. Flags: --top-k, --threshold, --method semantic. Search requires a table built with an embedding function on a source field, so tbl.search(text) auto-embeds the query. The Node example under examples/typescript/lancedb/ builds such a table and produces the same output as the Python example, including identical similarity scores (0.2679).

Getting Started

AI Agents

VFS

CLIs

Watch

Runtimes

Node

Filesystem layout

Cloud and Enterprise

Supported commands

​Node

​Filesystem layout

​Cloud and Enterprise

​Supported commands

Node

Filesystem layout

Cloud and Enterprise

Supported commands