Qdrant

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}

Semantic search

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.

Command	Behaviour on a Qdrant mount
`ls`	list collections, payload folders, or point files
`cd`	navigate (each level narrows the filter)
`tree`	render the folder hierarchy
`cat`	print a point’s text/JSON, or dump raw blob/image bytes
`stat`	directory vs file, blob size, image mime type
`find`	walk the tree (e.g. `find /fashion -name '*.txt'`)
`grep` / `rg`	lexical search over the text/JSON files
`search`	semantic (vector) search -> ranked content paths + score
`head` / `tail`	first/last lines of a file
`wc`	count 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.

Getting Started

Agents

Resources

CLIs

Watch

Runtimes

Config

Filesystem layout

Point files

Semantic search

Supported commands

Access pattern

​Config

​Filesystem layout

​Point files

​Semantic search

​Supported commands

​Access pattern

Config

Filesystem layout

Point files

Semantic search

Supported commands

Access pattern