UrnaFile

urna.UrnaFile is a read-only, memory-mapped handle on one .urna file. It has one constructor (open), 13 read-only properties and 11 methods: five search paths, retrieve, and six accessors for ids, blobs, metadata and validation.

Open a fileCopy Anchor Link

import urna

db = urna.open("corpus.urna")          # or urna.UrnaFile.open("corpus.urna")

UrnaFile.open(path: str) -> UrnaFile   # staticmethod

open maps the file read-only and validates all of it before it returns: magic (URNA, or the legacy NEST of 0.4.0), version, header checksum, file size, section bounds and alignment, the encoding and checksum of every section, the manifest and its contract, the footer hash, header and manifest agreement, and a walk of the embeddings for NaN and Inf. It then decodes chunk ids, spans, and any HNSW, BM25, graph, blob and space sections. Any failure raises ValueError, so an object you hold has already passed validation.

Because there is no close(), drop every reference to the object before you replace or delete the file. On Windows a mapped file cannot be deleted.

PropertiesCopy Anchor Link

All properties are read-only.

What each hash covers is on Citations and hashes.

Query vectors and kCopy Anchor Link

Every search method takes a query vector and k. The same rules apply to all of them.

The runtime cannot tell which model embedded a bare vector. Only retrieve and search_space can check the model, and only when you pass expected_model_hash.

Search methodsCopy Anchor Link

Every search method returns a list of SearchHit, best score first. score is always the exact cosine between the query and the stored vector, whichever path found the candidate. How the paths differ is on Search paths and the exact rerank.

searchCopy Anchor Link

UrnaFile.search(query, k) -> list[SearchHit]

Exact cosine over every row. Recall is 1.0. Hits report index_type="exact" and reranked=False.

search_annCopy Anchor Link

UrnaFile.search_ann(query, k, ef) -> list[SearchHit]

HNSW collects candidates, then every candidate is rescored with exact cosine. Hits report index_type="hnsw" and reranked=True. Without an HNSW section it runs search() and the hits report index_type="exact".

search_hybridCopy Anchor Link

UrnaFile.search_hybrid(query, query_text, k, candidates) -> list[SearchHit]

The vector leg takes HNSW with a beam of at least candidates and k, or the exact top candidates when the file has no HNSW. The BM25 leg takes its top candidates for query_text. The two lists are united with reciprocal-rank fusion, and every member of the union is rescored with exact cosine. Hits report index_type="hybrid" and reranked=True.

There is no fallback to search(). Without a BM25 section the lexical leg is empty and the hits still say "hybrid". Without HNSW and with candidates smaller than k, you get fewer than k hits, and candidates=0 returns [].

search_graphCopy Anchor Link

UrnaFile.search_graph(query, k, hops=1, ef=100) -> list[SearchHit]

Scores every row to pick the seeds, expands hops over the chunk graph (the frontier is capped at 8 times the seeds), then reranks the union with exact cosine. Hits report index_type="graph" and reranked=True. Without a graph section it runs search().

search_spaceCopy Anchor Link

UrnaFile.search_space(name, query, k, expected_model_hash=None) -> list[SearchHit]

Exact cosine over one named space. There is no fallback to the text vectors. An unknown name raises ValueError: embedding space not found: <name>, checked before the hash. A hash that differs raises ValueError: model_hash mismatch in space <name>: the query was embedded with ..., but the space vectors were embedded with .... The query length must equal the space dimension, not embedding_dim.

Hits report index_type="space" and reranked=False. Their embedding_model field still names the text model of the corpus, not the space's model. Spaces are explained on Media and named spaces.

retrieveCopy Anchor Link

UrnaFile.retrieve(query, k, candidates=None, hops=1, ef=100, expected_model_hash=None) -> list[RetrieveHit]

Returns a list of RetrieveHit: the fields of a search hit plus the stored text of the chunk and the precision the rerank read.

retrieve runs three steps.

1. The model gate, only when expected_model_hash is given. A mismatch raises before the query is even parsed.
2. A search, routed by the manifest index_type.
3. The stored canonical text is attached to each hit by chunk_id. This is the same text urna cite returns, never a reread of the original source.

cand is candidates, or max(4 * k, 64) when it is None. The code also has a graph route, but the manifest admits only exact, hnsw and hybrid, so no file reaches it and hops has no effect today. Python has no query_text parameter, so on a "hybrid" file the BM25 leg of retrieve gets an empty string and adds nothing. To use BM25 from Python, call search_hybrid yourself.

hits = db.retrieve(qvec, 5, expected_model_hash=emb.model_hash())

Other methodsCopy Anchor Link

chunk_idsCopy Anchor Link

UrnaFile.chunk_ids() -> list[str]

Every chunk_id in file order, which is the order the chunks were given to the builder. Each call returns a new list. The position of a hit in this list is its ordinal: db.chunk_ids().index(hit.chunk_id).

blob_refsCopy Anchor Link

UrnaFile.blob_refs() -> list[dict]

The blob_refs (0x14) table, one dict per media blob, in table order. Returns [] when the file has no blobs.

blob_bytesCopy Anchor Link

UrnaFile.blob_bytes(index: int) -> bytes

The bytes of one inlined blob, by its position in blob_refs(). When the blob is not inlined, when the index is out of range, or when the file has no blobs, it raises ValueError: blob <i> is not inlined in this file: open the media sidecar named by its blob_refs uri, or rebuild with [output] embed_media. A negative index raises OverflowError.

inspectCopy Anchor Link

UrnaFile.inspect() -> dict

The same document as urna inspect --json, parsed into a dict.

The manifest fields are described on Manifest.

validateCopy Anchor Link

UrnaFile.validate() -> bool

Re-reads the mapped file and checks it again: every checksum, the footer hash, the manifest contract, the NaN and Inf walk, and the search contract. Returns True, or raises ValueError.

validate() does not check inlined blobs against their blob_refs SHA-256. The Rust urna validate does. For a file with inlined media, run the binary.

Cost and concurrencyCopy Anchor Link

• retrieve decodes the canonical text of every chunk on each call to attach text to the hits. On a large corpus that decode dominates the call. If you only need ids and scores, call a search method.
• chunk_ids() copies the full list on each call. Keep the result if you need it more than once.
• search_graph scores every row to pick its seeds.
• No method releases the GIL, so threads in one process do not search in parallel. For parallel queries, run several processes, each with its own urna.open.

Hit fields are on SearchHit and RetrieveHit.