Skip to main content
LanceDBVFS mounts a LanceDB table, read-only, as nested folders, one level per group-by column. Each row is a Markdown card plus an optional blob file, such as its image. Set up the local, object storage and LanceDB Cloud connections as in LanceDB setup.

Install

Configure

idColumn (default id) names each row’s files. Without table, every table is a top-level folder.

Fields

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

Authentication

A local directory needs no credentials. LanceDB Cloud takes its db:// URI with apiKey and region (default us-east-1); LanceDB Enterprise adds its endpoint in hostOverride. An s3://, gs:// or az:// URI takes the store’s credentials or endpoint in storageOptions.

Layout

Each folder level filters on one groupBy column, in order: /fashion/Men/Shoes/White/ lists the rows whose gender is Men, articleType is Shoes and baseColour is White. Once every column is bound, the folder lists each row’s <id>.md and, with blobColumn, its <id>.<blobExt>. A value holding / renders as ∕, and a blank or dot-led value is led by ⁄, so every value keeps its own folder that lists and opens. A card lists the row’s columns, headed by titleColumn, without the vector and blob columns.

Behavior

  • Read-only: no command changes the table.
  • Listing cap: one folder listing reads at most maxRows (1,000) rows; rows past it are left out. Keep groupBy to low-cardinality columns on a large table.
The search CLI runs LanceDB’s vector search with the table’s embedding function, so the table needs one on a source column. Register it on the workspace:
Each hit prints its card’s path with the vector distance, then the card, so results work with cat, pipes and wc:
--top-k defaults to searchLimit (10). --threshold is the largest distance kept. --method takes only semantic.

Integration

LanceDB answers this command through its own API, so fewer cards are read. See Integration.
  • grep -r and rg: a LIKE query over each row’s string columns picks the cards to read, for any text, and misses nothing. 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.

VFS.md

The VFS.md an agent reads with LanceDB mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • Directories are the configured group-by columns; descending one narrows a filter.
  • Each matching row is a <id>.md card plus a <id>.<ext> blob file.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.