Presets and stored precision

A .urna file stores one embedding per chunk, and you choose the precision it is stored at. Lower precision makes the file smaller and moves scores slightly away from the float32 values. A build preset bundles that choice with the text encoding and the index sections; this page explains the trade, and Build presets lists the exact settings.

The four stored precisionsCopy Anchor Link

int8 and int4 sections also carry an 8-byte header. At dim 384 a vector takes 1,536 bytes as float32, 768 as float16, 388 as int8 and 204 as int4.

The dtype applies to the default space (section 0x04). Named spaces have their own dtype, set per model with space_dtype in the build spec (see Media and named spaces).

Truncation is a second axisCopy Anchor Link

mrl_dim keeps only the first K components of every vector and L2-normalizes the prefix again, before quantization and before the HNSW index is built. It multiplies with the dtype: int8 at mrl_dim = 256 is the micro point.

Truncation only makes sense for a model trained for it (matryoshka representation learning), where the first components carry most of the meaning. The file records mrl_dim and full_dim, urna stats prints them, and urna ask slices the query to the same length. A query at the full dim against a truncated file is a dimension mismatch. With int4, K must be a multiple of 64.

Size against recallCopy Anchor Link

The repository publishes one measured run of the whole curve in data/measure/ladder.json:

The size ratio is the whole file against the exact build, text and indexes included. The run used data/corpus_next.v1.urna (30,725 chunks, dim 384, a MiniLM model not trained for truncation), 100 queries, k = 10, on the NEON backend.

On this corpus, nano (full dim, int4) keeps more recall than any truncated point, and truncation costs recall at every step, because MiniLM was not trained for it. Reach for mrl_dim when raw size matters more than the last recall points, or when the model is trained for truncation.

How a score is computedCopy Anchor Link

Every score urna returns is a cosine recomputed by an exact rerank. HNSW, the chunk graph and BM25 only choose candidates; each candidate is then scored against the query with the same kernel the flat scan uses. The candidate list can miss a chunk, but a score is never an index-side estimate.

The rerank reads one source: a full-precision slab (section 0x09) when the file has one, otherwise the stored embeddings (0x04). The reader accepts a 0x09 slab, but no 0.5.1 writer emits one. So in practice:

• A float32 file reranks at full precision.
• A float16, int8 or int4 file reranks at stored precision: the query stays float32 and is scored against the stored codes and scales, with float32 accumulation.

"Real cosine at stored precision" is still a cosine between the query and the vector the file holds, not an approximation from the index. It differs from the float32 cosine by the quantization error of the stored vector.

The rerank source is disclosedCopy Anchor Link

The rerank source is reported, so a reader never has to guess which kind of score they got.

urna ask --disclose explain prints it before the answer:

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

On a float16, int8 or int4 file the line reads real cosine at stored precision. urna retrieve writes the same fact on every hit as "rerank_source": "full_precision" or "stored_precision", and so does RetrieveHit.rerank_source in Python. urna stats prints the dtype, and mrl_dim and full_dim when the file is truncated.

Choosing a presetCopy Anchor Link

• exact when file size is not the constraint, or when you need the float32 ground truth to compare other builds against.
• compressed for a file about a third the size with scores at float16. There is no index, so every query scans all vectors.
• tiny for about a quarter of the size, with an HNSW index for large corpora and int8 scores.
• nano for the smallest full-dim file, when the dim is a multiple of 64 and the recall above is acceptable for your data.
• micro (a recipe, built with dtype="int8", mrl_dim=256) only with a model trained for truncation, or when size wins over recall.
• hybrid writes float32 vectors, an HNSW index and a BM25 index. It is the default of urna build --spec.

Changing the preset changes content_hash, and with it every citation: the dtype, the truncation and the index type are all part of the hashed content. Pick the preset before you publish citations. The search routes themselves are described in Search paths and the exact rerank.