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

# moorcheh search

> Semantic search with a text or vector query.

## Overview

Runs semantic search across one or more namespaces. Provide either `--query` (text) or `--query-vector-json` (vector array). Prints ranked results as JSON.

* **Text query** — embedded via Ollama; use with **text** namespaces. Add `#key:value` metadata filters or `#keyword` text filters at the **end** of `--query`
* **Vector query** — use with **vector** namespaces; array length must match `vector_dimension`

## Synopsis

```bash theme={null}
moorcheh search [options]
```

## Options

| Flag                  | Default                 | Description                                                                           |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------------- |
| `--base-url`          | `http://localhost:8080` | Moorcheh API base URL                                                                 |
| `--query`             | —                       | Text search query (required if `--query-vector-json` is not set)                      |
| `--query-vector-json` | —                       | JSON array string for vector search                                                   |
| `--namespaces`        | `""`                    | Comma-separated namespace names (at least one required)                               |
| `--top-k`             | `5`                     | Max results (server clamps **1–100**)                                                 |
| `--threshold`         | `0.0`                   | Score threshold (sent to API; filtering requires `kiosk_mode`, which is **API only**) |

<Note>
  Put metadata and keyword filters in `--query` using `#key:value` and `#keyword` at the end (e.g. `--query "product docs #department:engineering"`). On **Windows PowerShell**, escape vector JSON: `--query-vector-json '[0.1,0.2,0.3,0.4,0.5]'`.
</Note>

## Examples

```bash theme={null}
# Text search
moorcheh search \
  --query "on prem retrieval" \
  --namespaces my-documents \
  --top-k 5

# Multiple namespaces (comma-separated)
moorcheh search \
  --query "retrieval" \
  --namespaces docs,products \
  --top-k 10

# Metadata filter in query (#department:engineering)
moorcheh search \
  --query "product documentation #department:engineering" \
  --namespaces my-documents

# Combined metadata + keyword filters
moorcheh search \
  --query "machine learning #department:engineering #semantic" \
  --namespaces my-documents \
  --top-k 10

# Vector search (length must match namespace vector_dimension)
moorcheh search \
  --query-vector-json "[0.1,0.2,0.3,0.4,0.5]" \
  --namespaces my-embeddings \
  --top-k 5
```

## Output

Prints JSON from `POST /search`:

<ResponseField name="results" type="array">
  Ranked hits, highest score first. Empty when nothing matches.
</ResponseField>

<ResponseField name="results[].id" type="string">
  Item id.
</ResponseField>

<ResponseField name="results[].score" type="number">
  Similarity score (0–1), rounded to 6 decimal places.
</ResponseField>

<ResponseField name="results[].label" type="string">
  Relevance label (for example `"High Relevance"`, `"Close Match"`).
</ResponseField>

<ResponseField name="results[].metadata" type="object">
  Item metadata.
</ResponseField>

<ResponseField name="results[].text" type="string">
  Document text for text namespaces. Empty string `""` for vector namespaces.
</ResponseField>

<ResponseField name="execution_time" type="number">
  Total request time in seconds.
</ResponseField>

<ResponseField name="timings" type="object">
  Detailed timing breakdown for each search phase, in seconds.
</ResponseField>

<ResponseField name="status" type="string">
  `"error"` on validation failures (HTTP 400).
</ResponseField>

<ResponseField name="message" type="string">
  Error description when the request fails.
</ResponseField>

```json Example output (text search) theme={null}
{
  "results": [
    {
      "id": "doc-1",
      "score": 0.566222,
      "label": "High Relevance",
      "metadata": { "department": "engineering" },
      "text": "Get items test document"
    }
  ],
  "execution_time": 0.110644,
  "timings": {
    "parse_validate": 0.0,
    "prepare_vector": 0.110394,
    "fetch_data": 0.0,
    "calculate_distance": 0.0,
    "select_candidates": 0.0,
    "calculate_scores": 0.0,
    "reorder": 0.0,
    "format_response": 0.0,
    "total": 0.110644
  }
}
```

```json Example output (vector search) theme={null}
{
  "results": [
    {
      "id": "vec-1",
      "score": 1.0,
      "label": "Close Match",
      "metadata": { "source": "demo" },
      "text": ""
    }
  ],
  "execution_time": 0.000069,
  "timings": {
    "parse_validate": 0.0,
    "prepare_vector": 0.0,
    "fetch_data": 0.0,
    "calculate_distance": 0.0,
    "select_candidates": 0.0,
    "calculate_scores": 0.0,
    "reorder": 0.0,
    "format_response": 0.0,
    "total": 0.000069
  }
}
```

## Relevance labels

| Score range | Label               |
| ----------- | ------------------- |
| ≥ 0.894   | Close Match         |
| ≥ 0.632   | Very High Relevance |
| ≥ 0.447   | High Relevance      |
| ≥ 0.316   | Good Relevance      |
| ≥ 0.224   | Low Relevance       |
| ≥ 0.1     | Very Low Relevance  |
| \< 0.1      | Irrelevant          |

## Exit codes

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `0`  | Search completed (including empty `results`)           |
| `1`  | Missing `--query`, invalid JSON, API error (400), etc. |

## Important notes

<Warning>
  * Text search requires **Ollama** running for embeddings
  * `--namespaces` must include at least one valid namespace name
  * Text queries cannot search vector namespaces (and vice versa)
  * CLI validation errors (missing query) print to **stderr** without API JSON
</Warning>

## Related

* [API: Search](/on-prem/api-references/search/query)
* [Python: similarity\_search.query()](/on-prem/python-client/search/query)