Trait Scorer 

pub trait Scorer:
    DocSet
    + Send
    + Sync {
    // Required method
    fn score(&self) -> Score;

    // Provided methods
    fn supports_candidate_score_bounds(&self) -> bool { ... }
    fn candidate_score_upper_bound(&self) -> Score { ... }
    fn candidate_block_upper_bound(&mut self) -> Option<(DocId, Score)> { ... }
    fn advance_competitive_candidate(
        &mut self,
        _minimum: Score,
        _allow_equal: bool,
    ) -> DocId { ... }
    fn seed_ranked_score(&mut self, _limit: usize) -> Option<Score> { ... }
    fn supports_filtered_windows(&self) -> bool { ... }
    fn supports_score_batches(&self) -> bool { ... }
    fn fill_score_batch(
        &mut self,
        docs: &mut DocBatch,
        scores: &mut ScoreBatch,
    ) -> usize { ... }
    fn score_batch_matches(
        &mut self,
        docs: &DocBatch,
        len: usize,
        scores: &mut ScoreBatch,
        matches: &mut ScoreBatchMask,
    ) { ... }
    fn supports_score_windows(&self) -> bool { ... }
    fn accumulate_score_window(
        &mut self,
        base: DocId,
        scores: &mut [Score; 4096],
        bits: &mut DocWindow,
    ) { ... }
    fn fill_score_window(
        &mut self,
        base: DocId,
        scores: &mut [Score; 4096],
        bits: &mut DocWindow,
    ) { ... }
    fn advance_candidate(&mut self) -> DocId { ... }
    fn seek_candidate(&mut self, target: DocId) -> DocId { ... }
    fn confirm_candidate(&mut self) -> bool { ... }
    fn matched_positions(&self) -> Option<MatchedPositions> { ... }
    fn exact_ranked_count(&self) -> Option<u64> { ... }
    fn precomputed_top_k(
        &mut self,
        limit: usize,
        collect_positions: bool,
    ) -> Option<(Vec<SearchResult>, u32)> { ... }
}

Scored document stream: a DocSet that also provides scores.

Required Methods

fn score(&self) -> Score

Score for current document

Provided Methods

fn supports_candidate_score_bounds(&self) -> bool

Opt into final-score bounds before candidate confirmation. Only a top-level ranked collector may use this to omit matches; complete collectors and enclosing scorers retain exact traversal.

fn candidate_score_upper_bound(&self) -> Score

Conservative upper bound on score() if the current candidate confirms. Must include floating-point rounding and use this scorer’s final score space. The default never excludes a score.

fn candidate_block_upper_bound(&mut self) -> Option<(DocId, Score)>

Conservative final-score bound through an inclusive physical doc ID. The interval starts at the current candidate. Only a top-level ranked collector may skip it; exact/nested traversal stays unchanged. Returning None opts out for the remaining traversal. A skipped interval is left through seek_candidate, including deadline checks.

fn advance_competitive_candidate( &mut self, _minimum: Score, _allow_equal: bool, ) -> DocId

Advance while optionally omitting candidates whose final-score bound cannot compete with minimum. Only top-level ranked collection may call this. allow_equal = false certifies that every remaining stable ID loses an equal-score tie against the full local heap.

fn seed_ranked_score(&mut self, _limit: usize) -> Option<Score>

Optionally prove a lower bound on the kth best score using distinct real matches. Restore the current candidate unless cancelled. Emit no sampled hits; normal traversal still owns them. Only top-level ranked collection may use this hint. Equality remains competitive until its own heap resolves stable-ID ties.

fn supports_filtered_windows(&self) -> bool

Whether this scorer’s batches remain useful when every match needs a predicate check. Composite scorers can amortize child traversal; leaf bitmap production alone may cost more than a scalar pass once filtering visits every set bit again.

fn supports_score_batches(&self) -> bool

Whether compact exact-score batches amortize this scorer’s work.

fn fill_score_batch( &mut self, docs: &mut DocBatch, scores: &mut ScoreBatch, ) -> usize

Consume a sorted exact prefix, leaving the first unconsumed match. Scores correspond to docs[..returned_len]; zero means exhausted.

fn score_batch_matches( &mut self, docs: &DocBatch, len: usize, scores: &mut ScoreBatch, matches: &mut ScoreBatchMask, )

Probe sorted unique docs[..len] without changing their order. Set membership bits index the input and its exact final scores. The cursor remains at or beyond the last probe.

fn supports_score_windows(&self) -> bool

Whether score-only collection benefits from bounded score windows. Positions still require ordinary per-document collection.

fn accumulate_score_window( &mut self, base: DocId, scores: &mut [Score; 4096], bits: &mut DocWindow, )

Add each exact match’s final score in a forward-only document window. Existing values and membership bits are retained. A nested scorer contributes its complete score once, preserving its summation order. The cursor ends at the first match after the interval. Previously consumed matches stay consumed, just as with fill_doc_window.

fn fill_score_window( &mut self, base: DocId, scores: &mut [Score; 4096], bits: &mut DocWindow, )

Replace a bounded window of exact scores and membership. Only advertised through supports_score_windows when it is beneficial.

fn advance_candidate(&mut self) -> DocId

Move to the next candidate for a two-phase conjunction. Candidates may be false positives: the caller must call confirm_candidate before consuming scores or positions. Ordinary DocSet traversal remains exact, including after candidate traversal. The default simply advances the exact stream.

fn seek_candidate(&mut self, target: DocId) -> DocId

Seek a candidate at or beyond target, without skipping any possible exact match. See advance_candidate for the protocol.

fn confirm_candidate(&mut self) -> bool

Exactly verify the current candidate without advancing it. Repeated calls must agree unless cancellation ends the stream. Only a true result permits consuming its score/positions.

fn matched_positions(&self) -> Option<MatchedPositions>

Get matched positions for the current document (if available) Returns (field_id, positions) pairs where positions are encoded as per PositionMode

fn exact_ranked_count(&self) -> Option<u64>

Exact cardinality supplied only for an explicit top-level ranked count request. Ordinary streams and ranked scorers return None.

fn precomputed_top_k( &mut self, limit: usize, collect_positions: bool, ) -> Option<(Vec<SearchResult>, u32)>

Standalone fast path for scorers that wrap an already ranked top-k list (text and vector executors). When this query is the top-level query of a segment search, the caller may take the ranked list directly instead of walking the DocSet and re-collecting it: the result must be exactly what a TopKCollector of size limit would produce (score desc, doc id asc, total_seen).

Only valid before the first advance/seek. Default: None (the scorer must be driven).

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Scorer for AllDocSet

impl Scorer for EmptyScorer

impl Scorer for PredicatedScorer<'_>