Skip to main content
The Qdrant resource mounts a Qdrant collection as a filesystem: group-by payload fields become folders, points become files, and semantic search is the search command. See Qdrant Resource for the full layout and command list.

​
Dependencies

uv add 'mirage-ai[qdrant]'
The qdrant extra installs qdrant-client[fastembed]. fastembed powers local, in-process query embedding for the search command; filesystem browsing (ls/cat/find/grep) needs only the base client.

​
Connection

The same QdrantConfig works for self-hosted and cloud.

​
Self-hosted

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

config = QdrantConfig(
    host="localhost",
    port=6333,
    collection="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_field="id",
    text_field="productDisplayName",
    blob_field="image_b64",
    blob_ext="jpg",
)
ws = Workspace({"/fashion/": QdrantResource(config)}, mode=MountMode.READ)

​
Qdrant Cloud

Use url plus an api_key: 
import os

config = QdrantConfig(
    url="https://xyz.cloud.qdrant.io",
    api_key=os.environ["QDRANT_API_KEY"],
    collection="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_field="id",
)
ws = Workspace({"/fashion/": QdrantResource(config)}, mode=MountMode.READ)

​
Search setup

The search command embeds the query and runs Qdrant vector search. The collection must already store vectors produced by the same model (embedding_model, default sentence-transformers/all-MiniLM-L6-v2). Query embedding happens one of two ways:
  • Local (default): fastembed embeds the query in process.
  • Server-side: set cloud_inference=True to have an inference-enabled Qdrant Cloud cluster embed the query. The query text is sent to the server instead of being embedded locally.
config = QdrantConfig(
    url="https://xyz.cloud.qdrant.io",
    api_key=os.environ["QDRANT_API_KEY"],
    collection="fashion",
    group_by=["gender"],
    cloud_inference=True,
    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
)

search "red running shoes" /fashion          # ranked <path>.txt:score + content
cat /fashion/Men/Shoes/White/3.txt            # follow a result to the real file

​
Config reference

FieldRequiredDefaultDescription
urlNoQdrant URL (Cloud or self-hosted); overrides host/port
hostNolocalhostHost when url is unset
portNo6333Port when url is unset
httpsNofalseUse TLS for host/port connections
api_keyNoQdrant Cloud API key
collectionNoPin one collection; the mount root becomes that collection
group_byNo[]Payload fields that become nested folder levels
id_fieldNoidField name shown for the point id; names point files
text_fieldNoPayload field served as the <id>.txt embedded source text
blob_fieldNoPayload field served as the raw blob/image file
blob_extNobinExtension for the blob file (jpg, png, …)
vector_fieldNoPayload field holding a vector, omitted from <id>.json
search_limitNo10Default top-k returned by search
max_rowsNo1000Cap on points scanned per folder listing
embedding_modelNosentence-transformers/all-MiniLM-L6-v2Model used to embed the query
cloud_inferenceNofalseEmbed the query server-side instead of with local fastembed
The mount is read-only. See Qdrant Resource for the filesystem layout and supported commands.