Search paths and the exact rerank

urna has several ways to find candidate chunks and one way to score them. Every path, however it generates candidates, ends by recomputing the cosine between the query and each candidate from the stored vectors. The score you get back is that recomputed cosine, never an index distance or a fusion score.

The scoring contractCopy Anchor Link

Every file declares metric = "ip" and normalize = "l2": vectors are stored L2-normalized and scored by inner product, which on unit vectors is cosine similarity. Hits always report score_type: "cosine". The writer does not check the norm of the vectors it is given, so this holds when the embedder that built the file normalized its output, as the bundled embedders do.

Before any path runs, the runtime checks the query and stops with a typed error on the first problem:

1. k is greater than 0.
2. The query is not empty.
3. Its length equals the file's embedding_dim.
4. Every value is finite (no NaN or Inf).
5. Its norm is not zero.

Then it L2-normalizes the query, so you do not have to.

The pathsCopy Anchor Link

The CLI prints a recall that was not measured as (not computed; rerank guarantees real cosine). The rerank guarantees that each returned score is a real cosine. It does not guarantee that an approximate path found the true top k; measure that with urna benchmark --ann.

ExactCopy Anchor Link

The exact path scores every chunk and sorts, with ties kept in file order. It is the ground truth the other paths are compared against.

HNSWCopy Anchor Link

The HNSW path walks the graph stored in hnsw_index to collect a candidate list, then reranks it exactly. If the file has no HNSW section, the path falls back to exact and the result says index_type: exact.

The beam width is max(ef, k, ef_construction), where ef_construction is the value the file was built with. Python and the forge build with ef_construction = 400.

HybridCopy Anchor Link

The hybrid path builds two shortlists. The vector shortlist comes from HNSW when the file has it (with the same beam floor as above), else it is the top candidates_per_path of an exact scan. The BM25 shortlist is the top candidates_per_path chunks by BM25 over the stored text. There is no BM25-only path: BM25 runs only inside hybrid. The path merges the two lists with reciprocal-rank fusion (RRF, k = 60), rescores every member of the merged set by exact cosine, and returns the top k by cosine.

That last step defines what hybrid does in urna: the RRF order is discarded and the final order is pure cosine. BM25 can bring a chunk into the candidate set that the vector shortlist missed; it never lifts a chunk above one with a higher cosine. A rare term or proper noun only reaches the top k if its chunk's cosine earns it.

Two edge cases:

• The path never falls back. Without a BM25 section the lexical list is empty and the route is still hybrid.
• Without HNSW, the vector shortlist holds at most candidates_per_path chunks, with no minimum of k. With no HNSW, no BM25 and candidates_per_path below k, fewer than k hits come back.

BM25 uses k1 = 1.5 and b = 0.75. Its tokenizer lowercases runs of letters and digits, splits on anything else, and drops tokens shorter than 2 characters. There is no stemming and no stop-word list. A run with no spaces or punctuation stays one token, so an unspaced CJK clause only matches an identical whole run.

GraphCopy Anchor Link

The graph path seeds from the exact top max(ef, k) chunks, expands them over the chunk-to-chunk graph for hops steps (all edge types, capped at 8 times the seed count), and reranks the union exactly. If the file has no graph_adjacency section, or its manifest does not set capabilities_ext.graph_present, it falls back to exact.

Because the seeds already are the exact top max(ef, k) and the rerank uses the same scores and ordering, the hits equal the exact path's hits. The graph adds neighbours to the candidate set, but a neighbour cannot outrank a seed it would need to displace. The path costs an exact scan plus the traversal.

Named spacesCopy Anchor Link

A file can carry extra embedding spaces, for example an image tower next to the text embeddings (see Media and named spaces). A named-space search is an exact scan over one space's band. The query must come from that space's model and have that space's dim. Hits map back to the same chunks, so they carry the same chunk_id and citation as a text hit on that chunk. The text paths never read a space band, and a space search never falls back to the text embeddings.

How ask and retrieve choose a pathCopy Anchor Link

urna ask, urna retrieve and urna search-text embed the query text, pass it through the model gate, and then route on the manifest's declared index_type:

The manifest admits only exact, hnsw and hybrid, so none of these verbs takes the graph path. Routing does not look at which sections exist or at the capabilities flags; urna stats shows the index_type that decides it.

The quickstart corpus declares hnsw and also carries BM25 and a graph. ask --disclose explain shows the route it took:

urna ask examples/quickstart/out/quickstart.urna "can I use this offline" -k 1 --disclose explain

route:         hnsw
candidates:    exact=0 ann=12 bm25=0 graph=0 fusion=none
rerank_source: real cosine
recall:        (not computed; rerank guarantees real cosine)

The file has 12 chunks, so the HNSW candidate list is the whole corpus. BM25 and the graph are present and unused.

The rerank sourceCopy Anchor Link

The rerank reads vectors from one slab. When a full-precision slab (embeddings_fp, 0x09) is present, it reads that. Otherwise it reads the stored embeddings section at its stored dtype. No writer in 0.5.1 emits 0x09, so in practice the rerank reads the stored embeddings.

A stored-precision score is still a cosine recomputed from the vectors, not a proxy from the index. It is the cosine between the query and the quantized vector, so it can differ from the float32 score of the same pair. See Presets and stored precision.

Scoring runs on AVX2 (with FMA) on x86_64, NEON on aarch64, or a scalar fallback, detected once per process; float16 has no AVX2 kernel and scores with the scalar kernel on x86_64. Set URNA_FORCE_SCALAR to any value other than 0 to force the scalar kernels (see Environment variables). The int4 kernel gives bit-identical scores on all three.

The per-verb flags are in the reference, starting with urna search.