Search

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)

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]

Search errors return "status": "error" with HTTP 400. Non-2xx responses raise MoorchehApiError.

API: POST /search — see Search

Parameters

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.

array

required

Non-empty list of namespace names to search. Each namespace must exist and match the query type (text vs vector).

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

number

default:"0"

Minimum score threshold (0–1). Used when kiosk_mode is true.

boolean

default:"false"

When true, threshold is required and results below the threshold are filtered out.

Examples — text search

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

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

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

array

Ranked search hits, highest score first. Empty array when nothing matches (including strict metadata filters).

string

Item id in the namespace.

string

Namespace that owns this result.

number

Similarity score between 0 and 1, rounded to 6 decimal places.

string

Human-readable relevance label derived from the score (see table below).

object

Metadata stored with the item. The top content hit may include summary_text (batch summary for uploaded file chunks).

string

Document text for text namespace hits. Empty string "" for vector namespace hits.

number

Total request time in seconds.

object

Detailed timing breakdown for each search phase, in seconds.

string

"error" on validation or search failures (HTTP 400). Present in MoorchehApiError.body, not in successful responses.

string

Error description when the request fails.

Example return value (text search)

{
  "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,
  },
}

Example return value (vector search)

{
  "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.

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`

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

Getting Started

System

Namespace Management

AI Generation

Data Operations

File storage

Items

Search

similarity_search.query

Parameters

Examples — text search

Example — vector search

Examples — kiosk mode

Returns

Relevance labels

Error Handling

​similarity_search.query

​Parameters

​Examples — text search

​Example — vector search

​Examples — kiosk mode

​Returns

​Relevance labels

​Error Handling

​Related Operations

similarity_search.query

Parameters

Examples — text search

Example — vector search

Examples — kiosk mode

Returns

Relevance labels

Error Handling

Related Operations