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

# search

> Rank the records of Dify, Chroma, mem0, Qdrant and LanceDB mounts for a query.

`search` asks a mount's own search to rank its records for a query: Dify's
retrieval API, Chroma's and Qdrant's vector queries, mem0's memory search and
LanceDB's vector search. Use it when meaning matters; `grep` and `rg` still
match exact text.

## Setup

`search` has no account config. It searches the mounts it is pointed at, so
register it on a workspace that mounts a store:

```typescript theme={null}
import { ChromaVFS, MountMode, SEARCH, Workspace } from '@struktoai/mirage-node'

const knowledge = new ChromaVFS({ config: { collectionName: 'docs' } })
const ws = new Workspace({ '/knowledge/': knowledge }, { mode: MountMode.READ })
ws.registerCli('search', SEARCH)
await ws.shell('search "how do I get started" /knowledge/')
```

Mounting a store does not register `search`. For YAML registration, see the
[CLI overview](https://docs.mirage.strukto.ai/typescript/cli/index.md#register-a-cli):

```yaml theme={null}
clis:
  search:
    cli: search
```

## Supported commands

Run `search --help` for the supported flags and operands.
This list is generated from Mirage's registered command tree.

| Command | Description |
| - | - |
| `search` | Rank the records of a search mount for a query |

## Usage

```bash theme={null}
search "how do I reset my password" /knowledge/
search --top-k 5 "billing policy" /knowledge/policies/ /knowledge/guides/
search --threshold 0.4 "quickstart" /knowledge/guides/*.md
```

| Argument | Meaning |
| - | - |
| `QUERY` | The text to rank records by. |
| `PATH ...` | Folders, files or globs to search; the working directory when none is given. Several are ranked as one query when one mount serves them all. |
| `--top-k N` | The most hits to print, 1 or more. Absent, the mount's default: 10, or the config's `searchLimit` on Qdrant and LanceDB and `defaultSearchLimit` on mem0. |
| `--threshold F` | The score a hit must reach, or on LanceDB the largest distance it may have; `0` keeps every hit. |
| `--method M` | `semantic`, the default. Dify also takes `fulltext`, `hybrid` and `keyword`. |

Each hit prints its path, then its score where the store ranks, then the
record's text:

```text theme={null}
/knowledge/policies/refunds:0.82
Refunds are allowed within 30 days.
```

A file the session cannot see is never printed.

## Mounts

| Mount | Searches with | `--threshold` |
| - | - | - |
| [Dify](https://docs.mirage.strukto.ai/python/vfs/dify.md#search) | The dataset retrieval API | Dify's score, from 0 to 1 |
| [Chroma](https://docs.mirage.strukto.ai/typescript/setup/chroma.md) | Chroma's vector query | 1 minus Chroma's distance |
| [mem0](https://docs.mirage.strukto.ai/typescript/setup/mem0.md) | mem0's memory search | mem0's score, from 0 to 1 |
| [Qdrant](https://docs.mirage.strukto.ai/typescript/setup/qdrant.md) | Qdrant's vector query | Qdrant's score |
| [LanceDB](https://docs.mirage.strukto.ai/typescript/setup/lancedb.md) | LanceDB's vector search | The largest distance kept |

A [custom VFS](https://docs.mirage.strukto.ai/typescript/vfs/new.md) joins the list by implementing `search`.

## Errors

| Line | Exit | Prints |
| - | - | - |
| No query, an empty one, `--top-k` below 1, an unknown option, or a value that is not a number | 2 | `search: query is required`, `search: top-k must be positive`, or the option error and `Try 'search --help' for more information.` |
| A value the mount does not take, such as `--method keyword` on Chroma or `--threshold 1.5` on Dify | 1 | The mount's reason, such as `search: only the 'semantic' method is supported` |
| A path that does not exist | 1 | `search: /knowledge/nope: No such file or directory` |
| A path on a mount without search | 1 | `search: /data: Operation not supported` |


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