Skip to main content
Qdrant mounts a collection as a read-only filesystem: group-by payload fields become nested folders, each point is a .json payload file (plus a .txt text file and an optional blob), and semantic search is the search CLI.

Connection

Local / self-hosted

Point host/port at a running Qdrant (defaults localhost:6333):

Qdrant Cloud

Use url plus an api_key:
Search is the search CLI’s search "<query>" <path>. It returns ranked points as their canonical <id>.txt (or <id>.json) file paths plus a similarity score, so results compose with cat, wc, and pipes (grep/rg stay lexical). The query text is turned into a vector two ways:
  • In process: pass an embed hook (text in, vector out) and your own model vectorizes the query, so a self-hosted Qdrant works.
  • Server-side: set cloud_inference to let a Qdrant Cloud (inference-enabled) cluster embed the query with embedding_model (default sentence-transformers/all-MiniLM-L6-v2).
With neither, search refuses the query. Either way the collection must already store vectors produced by the same model.

Limits

The VFS is read-only and bounds how much an agent can pull:
  • search_limit (10): default top-k returned by search.
  • max_rows (1,000): hard ceiling on points listed per folder.
Folder listings filter on payload fields. A filtered listing scrolls first and only creates keyword payload indexes for the group_by fields if Qdrant reports one is required. max_rows caps how many points are scanned per folder. For document/chunk collections, config field names accept dotted payload paths: use group_by=["metadata.source"], basename_fields=["metadata.source"], name_field="metadata.page", and text_field="page_content" to expose a source-document folder with readable page/chunk filenames. TypeScript uses the camelCase equivalents groupBy, basenameFields, nameField, and textField. See the Python and TypeScript VFS pages for full config.