moorcheh search

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

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)

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]'.

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

array

Ranked hits, highest score first. Empty when nothing matches.

string

Item id.

number

Similarity score (0–1), rounded to 6 decimal places.

string

Relevance label (for example "High Relevance", "Close Match").

object

Item metadata.

string

Document text for text namespaces. Empty string "" for vector namespaces.

number

Total request time in seconds.

object

Detailed timing breakdown for each search phase, in seconds.

string

"error" on validation failures (HTTP 400).

string

Error description when the request fails.

Example output (text search)

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

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

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

Getting Started

Runtime

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

Overview

Synopsis

Options

Examples

Output

Relevance labels

Exit codes

Important notes

​Overview

​Synopsis

​Options

​Examples

​Output

​Relevance labels

​Exit codes

​Important notes

​Related

Overview

Synopsis

Options

Examples

Output

Relevance labels

Exit codes

Important notes

Related