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 local, object storage and LanceDB Cloud connections as in LanceDB setup.

Install

Configure

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

Fields

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

Layout

Each folder level filters on one group_by 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 blob_column, its <id>.<blob_ext>. 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 title_column, without the vector and blob columns:

Behavior

  • Read-only: no command changes the table.
  • Listing cap: one folder listing reads at most max_rows (1,000) rows; rows past it are left out. Keep group_by 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 search_limit (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.