> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Qdrant

> Set up a Qdrant connection for the Qdrant VFS.

[Qdrant](https://qdrant.tech/) 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` command.

## Connection

### Local / self-hosted

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

```bash theme={null}
# .env.development
QDRANT_HOST=localhost
QDRANT_PORT=6333
```

### Qdrant Cloud

Use `url` plus an `api_key`:

```bash theme={null}
# .env.development
QDRANT_URL=https://xyz.us-east4-0.gcp.cloud.qdrant.io
QDRANT_API_KEY=...
```

## Search

Search is the `search "<query>" <path>` command. 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:

* **Local (default):** the `qdrant-client[fastembed]` extra embeds the query in
  process with `embedding_model` (default `sentence-transformers/all-MiniLM-L6-v2`).
* **Server-side:** set `cloud_inference` to let a Qdrant Cloud (inference-enabled)
  cluster embed the query. The TypeScript backend has no in-process model, so it
  takes this path or a caller's `embed` hook, and refuses `search` with neither.

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](/python/vfs/qdrant) and [TypeScript](/typescript/setup/qdrant)
VFS pages for full config.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.