Skip to main content
Hybrid search combining BM25 keywords, vector embeddings, query expansion, and neural reranking. This is the recommended search command for best results.

​
Usage

qmd query [options] <query>
​
query
string
required
Natural language query or structured query document

​
Options

​
-c, --collection
string
Filter by collection name (can be specified multiple times). Defaults to all included collections.
​
-n
number
default:"5 (CLI), 20 (JSON/files)"
Maximum number of results
​
--all
boolean
default:"false"
Return all matches (use with --min-score)
​
--min-score
number
default:"0"
Minimum score threshold (0-1)
​
--full
boolean
default:"false"
Show full document instead of best chunk
​
--line-numbers
boolean
default:"false"
Add line numbers to output
​
--json
boolean
default:"false"
Output as JSON
​
--csv
boolean
default:"false"
Output as CSV
​
--md
boolean
default:"false"
Output as Markdown
​
--xml
boolean
default:"false"
Output as XML
​
--files
boolean
default:"false"
Output file paths only (with docid and score)

​
How It Works

Single-line natural language query: 
qmd query "how does authentication work"
  1. BM25 check — Fast keyword search for strong signals
  2. Query expansion — Generate lex/vec/hyde variations if needed
  3. Hybrid search — Combine BM25 + vector results using RRF
  4. Neural reranking — Score all chunks with cross-encoder model
  5. Best chunks — Return highest-scoring chunks per document

​
Structured Mode (advanced)

Multi-line query with explicit strategy per line: 
qmd query $'lex: authentication security login\nvec: auth workflow\nhyde: JWT tokens stored in cookies'
Each line must start with lex:, vec:, or hyde::
  • lex: BM25 keyword search (supports phrases, proximity, negation)
  • vec: Vector semantic search
  • hyde: Hypothetical document (generates text that would answer the query)

​
Query Syntax Grammar

query          = expand_query | query_document
expand_query   = text | explicit_expand
explicit_expand= "expand:" text
query_document = { typed_line }
typed_line     = type "" text newline
type           = "lex" | "vec" | "hyde"
text           = quoted_phrase | plain_text
quoted_phrase  = '"' { character } '"'
plain_text     = { character }
newline        = "\n"

​
Examples

​
Automatic Queries

# Natural language
qmd query "how does deployment work"

# Technical terms
qmd query "kubernetes ingress configuration"

# Specific collection
qmd query "meeting notes from March" -c journals

# Multiple collections
qmd query "API design" -c docs -c wiki

# High-quality results only
qmd query "error handling" --min-score 0.5 -n 10

​
Structured Queries

# Combine keyword + semantic
qmd query $'lex: CAP theorem consistency\nvec: distributed systems tradeoffs'

# Exact phrase + vector search
qmd query $'lex: "API gateway" authentication\nvec: microservices security'

# Hypothetical document search
qmd query $'hyde: The authentication system uses JWT tokens with refresh rotation...'

# Complex multi-strategy
qmd query $'lex: kubernetes deployment -docker\nvec: container orchestration\nhyde: Deploy to cluster using kubectl apply'

​
Query Expansion

When using automatic mode, QMD generates multiple query variations: 
Original: "how does auth work"
├─ lex: authentication authorization security login
├─ vec: authentication workflow authorization flow
└─ hyde: Authentication uses JWT tokens stored in cookies...
Expansion is skipped if BM25 finds strong keyword matches (score > 15).

​
Reranking Model

Default model: qwen3-reranker (Qwen/Qwen2.5-3B-Instruct-qn_k_m from Hugging Face)
  • Cross-encoder scoring for relevance
  • Processes all chunks from top documents
  • Selects best chunk per document

​
Performance

Typical query times:
  • Strong BM25 signal: 50-100ms (skips expansion)
  • With expansion: 500ms-2s (embedding + reranking)
  • Large result sets: 2-5s (more chunks to rerank)
Progress feedback shown during:
  • Query expansion
  • Embedding generation
  • Reranking

qmd search

Fast BM25 keyword search only

qmd vsearch

Vector semantic search only

qmd embed

Generate embeddings

Search guide

Learn search strategies

Build docs developers (and LLMs) love

Get started for freeTalk to us