SearchHit and RetrieveHit

The search methods of UrnaFile return SearchHit objects, and UrnaFile.retrieve returns RetrieveHit objects. Both are read-only records with one attribute per field.

SearchHitCopy Anchor Link

Returned by search, search_ann, search_hybrid, search_graph and search_space. urna.SearchHit is the class (it prints as builtins.SearchHitPy), so isinstance(hit, urna.SearchHit) works. 12 fields:

A SearchHit carries no text. To get the stored text with the hit, call retrieve, or resolve the citation_id with urna cite.

RetrieveHitCopy Anchor Link

Returned by UrnaFile.retrieve. urna.RetrieveHit is the class (it prints as builtins.RetrieveHitPy). 11 fields, the same set the urna retrieve verb emits as JSON:

A RetrieveHit has no embedding_model, index_type or reranked. rerank_source tells you whether a score on a quantized file is the cosine of the original vectors or of their stored approximation. Presets and stored precision explains the difference.

OffsetsCopy Anchor Link

offset_start and offset_end hold whatever the builder wrote into byte_start and byte_end. They are byte offsets into the source only when the builder made them so:

Do not slice the original document with these offsets unless you know which builder made the file. Citations and hashes covers the same point for citations.

Object behaviorCopy Anchor Link

Hits are plain read-only records:

• repr() is the default <builtins.SearchHitPy object at 0x...>, with no field values.
• == compares identity, so two identical searches return hits that are not equal. Compare chunk_id or citation_id instead.
• They cannot be pickled (TypeError: cannot pickle 'builtins.SearchHitPy' object), have no __dict__ and no to_dict().
• They are not JSON serializable. Web frameworks cannot return them directly.

Copy the fields you need into a dict:

SEARCH_FIELDS = (
    "chunk_id", "score", "score_type", "source_uri", "offset_start", "offset_end",
    "embedding_model", "index_type", "reranked", "file_hash", "content_hash", "citation_id",
)
RETRIEVE_FIELDS = (
    "chunk_id", "score", "score_type", "source_uri", "offset_start", "offset_end",
    "citation_id", "text", "file_hash", "content_hash", "rerank_source",
)


def hit_to_dict(hit, fields):
    return {name: getattr(hit, name) for name in fields}


rows = [hit_to_dict(h, RETRIEVE_FIELDS) for h in db.retrieve(qvec, 5)]

Serve a corpus over HTTP uses the same pattern.