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

# Search

> Run semantic search using the Python client

## similarity\_search.query

Search stored items by semantic similarity and return ranked results with scores and relevance labels.

* **Text query** — string; embedded via your configured provider; search **text** namespaces. Use `#key:value` and `#keyword` for filtering
* **Vector query** — numeric array; search **vector** namespaces (length must match `vector_dimension`)

```python theme={null}
client.similarity_search.query(
    *,
    namespaces: list[str],
    query: str | list[float],
    top_k: int = 5,
    threshold: float = 0.0,
    kiosk_mode: bool = False,
) -> dict[str, Any]
```

<Note>
  Search errors return `"status": "error"` with HTTP **400**. Non-2xx responses raise `MoorchehApiError`.
</Note>

**API:** `POST /search` — see [Search](/on-prem/api-references/search/query)

### Parameters

<ParamField body="query" type="string | array" required>
  Text string or array of numbers. Text queries support `#key:value` metadata filters and `#keyword` text filters at the end of the string.
</ParamField>

<ParamField body="namespaces" type="array" required>
  Non-empty list of namespace names to search. Each namespace must exist and match the query type (text vs vector).
</ParamField>

<ParamField body="top_k" type="number" default="5">
  Maximum number of results to return. Clamped to **1–100**. Default is `5` in the client (server default is `10` if omitted in raw API calls).
</ParamField>

<ParamField body="threshold" type="number" default="0">
  Minimum score threshold (**0–1**). Used when `kiosk_mode` is `true`.
</ParamField>

<ParamField body="kiosk_mode" type="boolean" default="false">
  When `true`, `threshold` is **required** and results below the threshold are filtered out.
</ParamField>

### Examples — text search

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    response = client.similarity_search.query(
        query="product documentation #department:engineering #semantic",
        namespaces=["my-documents"],
        top_k=5,
    )

    for hit in response["results"]:
        print(hit["id"], hit["score"], hit["label"], hit.get("text"))
```

## Example — vector search

```python theme={null}
with MoorchehClient("http://localhost:8080") as client:
    response = client.similarity_search.query(
        query=[0.1, 0.2, 0.3, 0.4, 0.5],  # length must match vector namespaces
        namespaces=["my-embeddings"],
        top_k=5,
    )

    for hit in response["results"]:
        print(hit["id"], hit["score"], hit["label"], hit["metadata"])
```

### Examples — kiosk mode

```python theme={null}
with MoorchehClient("http://localhost:8080") as client:
    response = client.similarity_search.query(
        query="on prem retrieval",
        namespaces=["my-documents"],
        top_k=10,
        kiosk_mode=True,
        threshold=0.4,
    )
```

## Returns

<ResponseField name="results" type="array">
  Ranked search hits, highest score first. Empty array when nothing matches (including strict metadata filters).
</ResponseField>

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

<ResponseField name="results[].namespace" type="string">
  Namespace that owns this result.
</ResponseField>

<ResponseField name="results[].score" type="number">
  Similarity score between **0** and **1**, rounded to 6 decimal places.
</ResponseField>

<ResponseField name="results[].label" type="string">
  Human-readable relevance label derived from the score (see table below).
</ResponseField>

<ResponseField name="results[].metadata" type="object">
  Metadata stored with the item. The top content hit may include `summary_text` (batch summary for uploaded file chunks).
</ResponseField>

<ResponseField name="results[].text" type="string">
  Document text for **text** namespace hits. Empty string `""` for **vector** namespace hits.
</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 or search failures (HTTP 400). Present in `MoorchehApiError.body`, not in successful responses.
</ResponseField>

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

```python Example return value (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.108234,
  "timings": {
    "parse_validate": 0.0,
    "prepare_vector": 0.107252,
    "fetch_data": 0.0,
    "calculate_distance": 0.000336,
    "select_candidates": 0.0,
    "calculate_scores": 0.000072,
    "reorder": 0.0,
    "format_response": 0.0,
    "total": 0.108234,
  },
}
```

```python Example return value (vector search) theme={null}
{
  "results": [
    {
      "id": "vec-1",
      "score": 1.0,
      "label": "Close Match",
      "metadata": {"source": "demo"},
      "text": "",
    },
  ],
  "execution_time": 0.000015,
  "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.000015,
  },
}
```

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

### Error Handling

Non-2xx responses raise `MoorchehApiError`. Search validation errors use HTTP **400** with `"status": "error"` in the body.

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        response = client.similarity_search.query(
            query="test",
            namespaces=["my-documents"],
        )
except MoorchehApiError as e:
    print(e.status_code, e.body)  # e.body may include status: "error"
```

| Status | Cause                                                                                                                                                    |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Empty `query` or `namespaces`, namespace not found, query type mismatch, vector dimension mismatch, invalid `top_k`, or `kiosk_mode` without `threshold` |

<Warning>
  * Text search requires a configured embedding provider (Ollama, OpenAI, or Cohere)
  * You cannot search text namespaces with a vector query or vice versa
  * Use `#key:value` and `#keyword` at the end of text queries for filtering (same as cloud Moorcheh)
  * With `kiosk_mode: True`, set `threshold` (0–1) to control minimum relevance
</Warning>

## Related Operations

* [Upload Documents](/on-prem/python-client/data/upload-documents)
* [Upload Vectors](/on-prem/python-client/data/upload-vectors)
* [API: Search](/on-prem/api-references/search/query)
* [CLI: moorcheh search](/on-prem/cli/search/query)