pub struct SearchHit {
pub node: NodeRowLite,
pub score: f64,
pub modality: RetrievalModality,
pub source: SearchHitSource,
pub match_mode: Option<SearchMatchMode>,
pub snippet: Option<String>,
pub written_at: i64,
pub projection_row_id: Option<String>,
pub vector_distance: Option<f64>,
pub attribution: Option<HitAttribution>,
}Expand description
A single result row emitted by adaptive text search.
Fields§
§node: NodeRowLiteThe matched node, projected in the same shape the flat query surface uses.
score: f64Raw engine score used for ordering within a block. Higher is always better, across every modality and every source:
- Text hits: the FTS5 bm25 score with its sign flipped (
-bm25(...)), so higher score corresponds to stronger lexical relevance. - Vector hits: a negated distance (
-vector_distance) for distance metrics, or a direct similarity value for similarity metrics.
Scores are ordering-only within a block. Scores from different blocks — and in particular text scores vs. vector scores — are not on a shared scale. The engine does not normalize across blocks, and callers must not compare or arithmetically combine scores across blocks.
modality: RetrievalModalityCoarse retrieval-modality classifier. Every hit produced by the
current text execution paths is tagged
RetrievalModality::Text; future phases that wire vector
retrieval will tag those hits RetrievalModality::Vector.
source: SearchHitSourceWhich FTS surface produced the hit.
match_mode: Option<SearchMatchMode>Whether this hit came from the strict or relaxed branch. Some
for every text hit; reserved as None for future vector hits,
which have no strict/relaxed notion.
snippet: Option<String>Short context snippet for display. Some for at least the chunk path
(SQLite’s snippet(...)) and a trimmed window of text_content for
the property path.
written_at: i64Wall-clock timestamp (unix seconds) at which the active version of the node was written.
Under fathomdb’s soft-delete supersession model, nodes are versioned:
each edit creates a new active row and marks the prior row
superseded. written_at reflects when the current active row was
inserted, which is “when the text that just matched was written,” not
“when the logical_id was first created.” A node created two years ago
but updated yesterday will show yesterday’s timestamp, because
yesterday’s text is what the FTS index scored against.
This is deliberately distinct from superseded_at (only populated on
dead rows), node_access_metadata.last_accessed_at (an explicit touch,
not a write), and provenance_events.created_at (audit event time).
projection_row_id: Option<String>Opaque identifier of the underlying projection row (e.g. chunks.id
for chunk hits, or fts_node_properties.rowid for property hits).
Useful for debugging and for future attribution paths.
vector_distance: Option<f64>Raw vector distance or similarity for vector hits. None for text
hits.
Stable public API: this field ships in v1 and is documented as
modality-specific diagnostic data. Callers may read it for display
or internal reranking but must not compare it against text-hit
score values or use it arithmetically alongside text scores — the
two are not on a shared scale.
For distance metrics the raw distance is preserved (lower = closer
match); callers that want a “higher is better” ordering value should
read score instead, which is already negated appropriately for
intra-block ranking.
attribution: Option<HitAttribution>Reserved: match-attribution payload. Always None in Phase 1.