Skip to main content
The Qdrant resource exposes a Qdrant collection as a virtual filesystem mounted at some prefix such as /q/. Group-by payload fields become nested folders, each point becomes a .json payload file (plus a .txt text file and an optional blob), and semantic search is the search command, which returns ranked points as canonical file paths. For connection setup (self-hosted, Qdrant Cloud, search), see Qdrant Setup.

​
Config

from mirage import MountMode, Workspace
from mirage.resource.qdrant import QdrantConfig, QdrantResource

config = QdrantConfig(
    url="https://xyz.cloud.qdrant.io",
    api_key="...",
    collection="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_field="id",
    text_field="productDisplayName",
    blob_field="image_b64",
    blob_ext="jpg",
    search_limit=5,
)
resource = QdrantResource(config)
ws = Workspace({"/fashion/": resource}, mode=MountMode.READ)
The mapping is config-driven; nothing about the dataset is hardcoded. Point group_by at different payload fields and the folder tree changes.

​
Filesystem layout

Every path is translated into a Qdrant query. Descending a folder adds one payload filter; the leaf level lists points. 
/                                  # list collections (omitted when `collection` is pinned)
/<collection>/                     # distinct group_by[0] values
  <v1>/                            # distinct group_by[1] where group_by[0]=v1
    .../<vN>/                      # all group-by fields bound -> point files
      <id>.json                    # full payload (the metadata)
      <id>.txt                     # embedded source text (when text_field set)
      <id>.<ext>                   # raw blob / image bytes (when blob_field set)
<id> is the Qdrant point id. When collection is set the collection level is elided, so the mount root is that collection: 
/fashion/
  Men/
    Shoes/
      White/
        3.json
        3.txt
        3.jpg

​
Point files

A point is shown as its underlying data in its original format, never as the embedding vector:
  • <id>.txt is the embedded source text (the text_field value), exactly what the vector was built from.
  • <id>.json is the full payload as compact JSON (the metadata), with the vector and the raw blob omitted.
  • <id>.<ext> is the raw blob bytes when blob_field is configured.
$ cat /fashion/Men/Shoes/White/3.txt
Nike Men White Running Sneakers

$ cat /fashion/Men/Shoes/White/3.json
{"gender":"Men","articleType":"Shoes","baseColour":"White","productDisplayName":"Nike Men White Running Sneakers","id":3}
Search is a command, not a path. It returns each ranked point as its canonical content path (the <id>.txt, or <id>.json when no text_field is set) annotated with the similarity score, followed by the content: 
$ search "white running sneakers" /fashion
/fashion/Men/Shoes/White/3.txt:0.7421
Nike Men White Running Sneakers
Flags: --top-k <n> (default search_limit), --threshold <min-score>, --method semantic (the only supported method; grep/rg stay lexical).

​
Supported commands

All commands delegate to Mirage’s shared implementations.
CommandBehaviour on a Qdrant mount
lslist collections, payload folders, or point files
cdnavigate (each level narrows the filter)
treerender the folder hierarchy
catprint a point’s text/JSON, or dump raw blob/image bytes
statdirectory vs file, blob size, image mime type
findwalk the tree (e.g. find /fashion -name '*.txt')
grep / rglexical search over the text/JSON files
searchsemantic (vector) search -> ranked content paths + score
head / tailfirst/last lines of a file
wccount lines/bytes of a file

​
Access pattern

The mount is read-only (MountMode.READ); writes are not supported. The two read modes are:
  • Browse by payload folders: scroll filters on group_by fields, no embedding.
  • Search by meaning: search "<query>" <path> runs vector search and returns canonical point paths.
Folder listings are capped by max_rows. A filtered listing scrolls first and only creates keyword payload indexes for the group_by fields if Qdrant reports one is required, so already-indexed collections work under read-only keys. Keep group_by to low-cardinality fields for large collections.