Vector query (kNN)

Vector query (kNN) #

Finds the k nearest neighbors of a query vector — similarity search over dense_vector / sparse_vector fields. The query vector can be supplied directly, or as natural-language text that the serving layer embeds with the field’s configured model (schema-driven semantic search).

How it works #

Execution depends on where the documents live:

• Realtime (not yet flushed) — an exact brute-force scan over the mutable store: every vector is scored, a size-k min-heap keeps the best, and a filter (see below) is tested before any distance is computed.
• Flushed segments — the field’s index_type decides: flat scans the stored f32 vectors (exact, O(N·dims)); the graph types (hnsw_flat, turbo_quant_hnsw, bbq_hnsw) traverse the persisted HNSW graph with distances computed on the flat vectors — scores stay exact and only an ef-bounded neighborhood is evaluated; the quantized scans (turbo_quant, bbq_flat) score compact codes for a k × oversampling candidate pool and rescore it with full precision (approximate). The per-type breakdown is in Index types.

Scores follow the field’s similarity (overridable per query, but it must match the schema): cosine is the cosine similarity in [-1.0, 1.0]; dot_product the raw dot product; l2 scores as the negated squared Euclidean distance — 0 means identical vectors. Higher is always more similar, so one top-k heap serves all three.

Hybrid search and scoring pipeline

Hybrid search and scoring pipeline #

Pizza runs lexical (BM25) and vector retrieval side by side and gives you explicit, composable stages to combine and re-shape scores:

graph LR B("bm25 leg") --> F("fuse
rrf / linear / disjmax") V("vector leg") --> F F --> SC("score_functions
per-document function scoring") P["a plain query,
no retrieve"] --> SC SC --> RS("rescore
second pass on the top window") RS --> H["one ranked list"]

Every stage is optional and combines with a plain query: use score_functions alone on a keyword search, or the full chain for hybrid retrieval.

Semantic query

Semantic query #

Semantic search with zero field knowledge: the vector field and the embedding model resolve from the collection schema, and the request is plain text — the retrieval question asked without naming a field, a model, or a vector.

Examples #

POST /my-collection/_search
{"query": {"semantic": "find documents about search engines"}}

The clause composes inside bool like any other leaf — the text is embedded and the clause rewritten before execution:

Lesson 6 — Hybrid search

Lesson 6 — Hybrid search #

Most engines hide their fusion behind a magic flag. Pizza exposes the retrieval pipeline as explicit request stages — retrieve runs retrievers in parallel, fuse merges them, and two more stages re-shape scores afterwards:

retrieve  →  fuse  →  score_functions  →  rescore
(parallel    (merge    (function           (second pass
 retrievers)  the lists) scoring)            on the top window)

Every stage is optional and combines with a plain query — you can use score_functions alone on a keyword search, or the full chain for hybrid retrieval.