> ## 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

> Virtualize a Qdrant collection from Node or the browser.

`QdrantVFS` mounts a [Qdrant](https://qdrant.tech/) collection, read-only, as
nested folders, one level per group-by payload field. Each point is a `.json`
payload file, plus a `.txt` text file and an optional blob. Set up the cluster URL and API key as in [Qdrant setup](https://docs.mirage.strukto.ai/home/setup/qdrant.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node @qdrant/js-client-rest
```

## Configure

```ts theme={null}
import { MountMode, QdrantVFS, Workspace } from '@struktoai/mirage-node'

const fashion = new QdrantVFS({
  url: process.env.QDRANT_URL!,
  apiKey: process.env.QDRANT_API_KEY!,
  collection: 'fashion',
  groupBy: ['gender', 'articleType', 'baseColour'],
  textField: 'productDisplayName',
})
const ws = new Workspace({ '/fashion': fashion }, { mode: MountMode.READ })

const result = await ws.shell('ls /fashion/Men/Shoes/White && cat /fashion/Men/Shoes/White/3.json')
console.log(result.stdoutText)
await ws.close()
```

A self-hosted Qdrant sets `host` and `port` (default `localhost:6333`) instead
of `url`. `blobField` and `blobExt` serve a payload field of raw or base64
bytes as a file, such as `3.jpg`.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**url** `string` (default: null)

Full URL of the Qdrant server, such as a Qdrant Cloud cluster URL; when set, `host`, `port` and `https` are ignored.

**host** `string` (default: 'localhost')

Host name of the Qdrant server when `url` is unset.

**port** `number` (default: 6333)

Port of the Qdrant server when `url` is unset.

**https** `boolean` (default: false)

Connect to `host` over HTTPS when `url` is unset.

**apiKey** `string` (default: null)

Qdrant API key, required by Qdrant Cloud.

**collection** `string` (default: null)

Collection the mount root shows; unset lists every collection as a top-level folder.

**groupBy** `string[]` (default: \[])

Payload fields that become folder levels, one per field in order; dotted paths reach nested keys. Unset puts every point's files directly under the collection.

**basenameFields** `string[]` (default: \[])

`groupBy` fields whose folder names keep only the last path or URL segment of the value; two values with one basename under the same parent are refused as a collision.

**idField** `string` (default: 'id')

Key the point id is written under in a point's `.json`; it replaces a payload field of that name.

**nameField** `string` (default: null)

Payload field whose value prefixes each point's file stem as `<name>__<id>`; unset names files by point id alone.

**textField** `string` (default: null)

Payload field served as the point's `.txt` file and printed by `search`; unset leaves no `.txt`, and `search` returns the `.json`.

**blobField** `string` (default: null)

Payload field of raw or base64 bytes served as `<id>.<blobExt>` and left out of the `.json`; unset adds no blob file.

**blobExt** `string` (default: 'bin')

File extension of the blob file, without the dot.

**vectorField** `string` (default: null)

Payload field holding a copy of the vector, left out of the `.json`.

**searchLimit** `number` (default: 10)

Results `search` returns when `--top-k` is not given.

**maxRows** `number` (default: 1000)

Most points one folder listing scrolls; points past it are left out, and a group folder lists only the values those points carry.

**embeddingModel** `string` (default: 'sentence-transformers/all-MiniLM-L6-v2')

Model the server embeds a `search` query with under `cloudInference`; it must match the model the stored vectors came from.

**cloudInference** `boolean` (default: false)

Send the `search` query text to the server to embed, which needs a cluster with inference enabled (Qdrant Cloud). `embed` takes precedence; with neither, `search` refuses the query.

**embed** `function` (default: null)

Async function that turns a `search` query into a vector in-process, `(text: string) => Promise<number[]>`.

Fields marked secret are redacted in snapshots.

## Authentication

A self-hosted Qdrant needs no key. Qdrant Cloud needs `apiKey`; a read-only
key, for the cluster or for the mounted collections, is enough to browse.

A filtered listing creates a keyword payload index for a `groupBy` field only
when Qdrant reports that one is required. A read-only key cannot create it, so
index those fields first or use a key that manages the collection.

## Layout

```text theme={null}
/fashion/
  Men/
    Shoes/
      White/
        3.json
        3.txt
  Women/
    Tops/
      Blue/
        12.json
        12.txt
```

Each folder level filters on one `groupBy` field, in order. Once every field is
bound, the folder lists each point's files, named by point id, or
`<name>__<id>` with `nameField`. Without `collection`, every collection is a
top-level folder. A value holding `/` renders as `∕`, and a blank or dot-led
value is led by `⁄`, so every value keeps its own folder that lists and opens.

* `<id>.txt` is the `textField` value, the text the vector was built from.
* `<id>.json` is the full payload as compact JSON, without the vector and the
  blob.
* `<id>.<blobExt>` is the raw bytes of `blobField`, when it is set.

## Behavior

* **Read-only:** no command changes the collection.
* **Nested fields:** fields take Qdrant's dotted keys. For LangChain-style
  chunks, `groupBy: ['metadata.source']`, `basenameFields: ['metadata.source']`,
  `nameField: 'metadata.page'` and `textField: 'page_content'` show page `004`
  of `s3://docs/policies/refund-2026.pdf` as
  `refund-2026.pdf/004__<point-id>.txt`.
* **File names:** the point id stays in every name, so two equal labels never
  collide. Only the name a listing shows opens: another label in front of the
  same id reads as absent. A label that is not a string is written as compact
  JSON (`true`, `1`, `1e-7`).
* **Basenames:** `basenameFields` keeps only the last path or URL segment of a
  value. Two values with one basename under the same parent are refused rather
  than merged, and opening a basename folder checks every point of its parent,
  so a second source past `maxRows` is refused rather than hidden. A name over
  255 bytes is cut to fit and ends in `__` plus the md5 of the whole name.
* **Listing cap:** one folder listing scrolls at most `maxRows` (1,000) points;
  points past it are left out. Keep `groupBy` to low-cardinality fields on a
  large collection.

### Semantic search

The `search` CLI runs Qdrant's vector query. Register
it on the workspace:

```ts theme={null}
import { SEARCH } from '@struktoai/mirage-node'

ws.registerCli('search', SEARCH)
```

Each hit prints the point's `.txt` path, or its `.json` without `textField`,
with the similarity score, then the content. `--top-k` defaults to
`searchLimit` (10). `--threshold` is the lowest score kept. `--method` takes
only `semantic`.

The query needs a vector. `embed`, a `(text: string) => Promise<number[]>`,
builds it in-process, so a self-hosted Qdrant works with any model. Without it,
`cloudInference: true` sends the query text to the cluster, which must have
inference enabled (Qdrant Cloud) and store vectors from the same
`embeddingModel`. With neither, `search` refuses the query. `embed` never lands
in a snapshot, so a restored mount needs a fresh `QdrantVFS`.

## Browser

The same `QdrantVFS` runs in the browser from `@struktoai/mirage-browser`.

```bash theme={null}
npm install @struktoai/mirage-browser @qdrant/js-client-rest
```

```ts theme={null}
import { MountMode, QdrantVFS, Workspace } from '@struktoai/mirage-browser'

const fashion = new QdrantVFS({
  url: 'https://xyz-example.eu-central.aws.cloud.qdrant.io:6333',
  apiKey: QDRANT_API_KEY,
  collection: 'fashion',
  groupBy: ['gender', 'articleType', 'baseColour'],
  textField: 'productDisplayName',
})
const ws = new Workspace({ '/fashion': fashion }, { mode: MountMode.READ })
```

* The page calls Qdrant directly, so the server must accept requests from the
  page's origin.
* The API key is visible to anyone who loads the page: use a read-only key
  limited to the mounted collections.

## Integration

Qdrant answers this command through its own API, so fewer files are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -r` and `rg`: one scroll per folder, as a listing does, picks the
  `.json` and `.txt` files whose text holds the pattern's text in any case, for
  ASCII text, and misses nothing. A point changed since the last listing is
  still found. A blob, a `.json` or `.txt` over 8 KiB, and every file for a
  text that is not ASCII are read as usual.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Qdrant mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `qdrant`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> * At the root each directory is a collection, unless config pins one.
> * Inside a collection, directories are the group-by payload fields;
>   descending one narrows a filter.
> * Each point is `<id>.json` (its payload), plus `<id>.txt` (source text)
>   and `<id>.<ext>` (blob bytes) when those fields are configured. The
>   vector is never shown.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `qdrant` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `qdrant`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> - At the root each directory is a collection, unless config pins one.
> - Inside a collection, directories are the group-by payload fields;
>   descending one narrows a filter.
> - Each point is `<id>.json` (its payload), plus `<id>.txt` (source text)
>   and `<id>.<ext>` (blob bytes) when those fields are configured. The
>   vector is never shown.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `qdrant` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


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