Skip to main content

​
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

​
query
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.
​
namespaces
array
required
Non-empty list of namespace names to search. Each namespace must exist and match the query type (text vs vector).
​
top_k
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).
​
threshold
number
default:"0"
Minimum score threshold (0–1). Used when kiosk_mode is true.
​
kiosk_mode
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"))

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

​
results
array
Ranked search hits, highest score first. Empty array when nothing matches (including strict metadata filters).
​
results[].id
string
Item id in the namespace.
​
results[].namespace
string
Namespace that owns this result.
​
results[].score
number
Similarity score between 0 and 1, rounded to 6 decimal places.
​
results[].label
string
Human-readable relevance label derived from the score (see table below).
​
results[].metadata
object
Metadata stored with the item. The top content hit may include summary_text (batch summary for uploaded file chunks).
​
results[].text
string
Document text for text namespace hits. Empty string "" for vector namespace hits.
​
execution_time
number
Total request time in seconds.
​
timings
object
Detailed timing breakdown for each search phase, in seconds.
​
status
string
"error" on validation or search failures (HTTP 400). Present in MoorchehApiError.body, not in successful responses.
​
message
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 rangeLabel
≥ 0.894Close Match
≥ 0.632Very High Relevance
≥ 0.447High Relevance
≥ 0.316Good Relevance
≥ 0.224Low Relevance
≥ 0.1Very Low Relevance
< 0.1Irrelevant

​
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"
StatusCause
400Empty 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