QdrantVFS mounts a Qdrant collection, read-only, as
nested folders, one level per group-by payload field. Each point is a .json
payload file, plus a .txt text file and an optional blob. Set up the cluster URL and API key as in Qdrant setup.
Install
Configure
host and port (default localhost:6333) instead
of url. blob_field and blob_ext serve a payload field of raw or base64
bytes as a file, such as 3.jpg.
Fields
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.
Full URL of the Qdrant server, such as a Qdrant Cloud cluster URL; when set,
host, port and https are ignored.Payload fields that become folder levels, one per field in order; dotted paths reach nested keys. Unset puts every point’s files directly under the collection.
group_by fields whose folder names keep only the last path or URL segment of the value; two values with one basename under the same parent are refused as a collision.Key the point id is written under in a point’s
.json; it replaces a payload field of that name.Payload field whose value prefixes each point’s file stem as
<name>__<id>; unset names files by point id alone.Payload field served as the point’s
.txt file and printed by search; unset leaves no .txt, and search returns the .json.Payload field of raw or base64 bytes served as
<id>.<blob_ext> and left out of the .json; unset adds no blob file.Most points one folder listing scrolls; points past it are left out, and a group folder lists only the values those points carry.
Model the server embeds a
search query with under cloud_inference; it must match the model the stored vectors came from.Send the
search query text to the server to embed, which needs a cluster with inference enabled (Qdrant Cloud). embed takes precedence; with neither, search refuses the query.Async function that turns a
search query into a vector in-process, (text: str) -> list[float].Authentication
A self-hosted Qdrant needs no key. Qdrant Cloud needsapi_key; a read-only
key, for the cluster or for the mounted collections, is enough to browse.
A filtered listing creates a keyword payload index for a group_by field only
when Qdrant reports that one is required. A read-only key cannot create it, so
index those fields first or use a key that manages the collection.
Layout
group_by field, in order. Once every field
is bound, the folder lists each point’s files, named by point id, or
<name>__<id> with name_field. Without collection, every collection is a
top-level folder. 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.
<id>.txtis thetext_fieldvalue, the text the vector was built from.<id>.jsonis the full payload as compact JSON, without the vector and the blob.<id>.<blob_ext>is the raw bytes ofblob_field, when it is set.
Behavior
- Read-only: no command changes the collection.
- Nested fields: fields take Qdrant’s dotted keys. For LangChain-style
chunks,
group_by=["metadata.source"],basename_fields=["metadata.source"],name_field="metadata.page"andtext_field="page_content"show page004ofs3://docs/policies/refund-2026.pdfasrefund-2026.pdf/004__<point-id>.txt. - File names: the point id stays in every name, so two equal labels never
collide. Only the name a listing shows opens: another label in front of the
same id reads as absent. A label that is not a string is written as compact
JSON (
true,1,1e-7). - Basenames:
basename_fieldskeeps only the last path or URL segment of a value. Two values with one basename under the same parent are refused rather than merged, and opening a basename folder checks every point of its parent, so a second source pastmax_rowsis refused rather than hidden. A name over 255 bytes is cut to fit and ends in__plus the md5 of the whole name. - Listing cap: one folder listing scrolls at most
max_rows(1,000) points; points past it are left out. Keepgroup_byto low-cardinality fields on a large collection.
Semantic search
Thesearch CLI runs Qdrant’s vector query. Register it
on the workspace:
.txt path, or its .json without text_field,
with the similarity score, then the content:
--top-k defaults to search_limit (10). --threshold is the lowest score
kept. --method takes only semantic.
The query needs a vector. embed, an async (text: str) -> list[float],
builds it in-process, so a self-hosted Qdrant works with any model.
Without it, cloud_inference=True sends the query text to the cluster, which
must have inference enabled (Qdrant Cloud) and store vectors from the same
embedding_model. With neither, search refuses the query. embed never
lands in a snapshot, so a restored mount needs a fresh QdrantVFS.
Integration
Qdrant answers this command through its own API, so fewer files are read. See Integration.grep -randrg: one scroll per folder, as a listing does, picks the.jsonand.txtfiles whose text holds the pattern’s text in any case, for ASCII text, and misses nothing. A point changed since the last listing is still found. A blob, a.jsonor.txtover 8 KiB, and every file for a text that is not ASCII are read as usual.
VFS.md
The VFS.md an agent reads with Qdrant mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- At the root each directory is a collection, unless config pins one.
- Inside a collection, directories are the group-by payload fields; descending one narrows a filter.
- Each point is
<id>.json(its payload), plus<id>.txt(source text) and<id>.<ext>(blob bytes) when those fields are configured. The vector is never shown.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.