Skip to main content

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.

​
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
  • Vector query — use with vector namespaces; array length must match vector_dimension

​
Synopsis

moorcheh search [options]

​
Options

FlagDefaultDescription
--base-urlhttp://localhost:8080Moorcheh 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-k5Max results (server clamps 1–100)
--threshold0.0Score threshold (sent to API; filtering requires kiosk_mode, which is API only)
--metadata-json{}JSON object metadata filter (exact key/value match)
On Windows PowerShell, escape JSON flags: --metadata-json '{\"team\":\"ai\"}', --query-vector-json '[0.1,0.2,0.3,0.4,0.5]'.

​
Examples

# 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
moorcheh search \
  --query "retrieval" \
  --namespaces my-documents \
  --metadata-json '{"team":"ai"}'

# 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:
​
results
array
Ranked hits, highest score first. Empty when nothing matches.
​
results[].id
string
Item id.
​
results[].score
number
Similarity score (0–1), rounded to 6 decimal places.
​
results[].label
string
Relevance label (for example "High Relevance", "Close Match").
​
results[].metadata
object
Item metadata.
​
results[].text
string
Document text for text namespaces. Empty string "" for vector namespaces.
​
execution_time
number
Total request time in seconds.
​
timings
object
Detailed timing breakdown for each search phase, in seconds.
​
status
string
"error" on validation failures (HTTP 400).
​
message
string
Error description when the request fails.
Example output (text search)
{
  "results": [
    {
      "id": "doc-1",
      "score": 0.566222,
      "label": "High Relevance",
      "metadata": { "team": "ai" },
      "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
  }
}
Example output (vector search)
{
  "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 rangeLabel
≥ 0.894Close Match
≥ 0.632Very High Relevance
≥ 0.447High Relevance
≥ 0.316Good Relevance
≥ 0.224Low Relevance
≥ 0.1Very Low Relevance
< 0.1Irrelevant

​
Exit codes

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

​
Important notes

  • 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