Struct PredicatedScorer 

pub struct PredicatedScorer<'a> { /* private fields */ }

Wraps a driving Scorer with filter conditions pushed down.

Used by the query planner to flip iteration order: the SHOULD scorer drives and MUST/MUST_NOT clauses are checked per-doc via:

• O(1) predicate closures (e.g., fast-field range checks)
• seek()-based verifier scorers (e.g., TermQuery posting list lookups)

Verifier scorers contribute their actual per-doc score (e.g., BM25).

Implementations

impl<'a> PredicatedScorer<'a>

pub fn new( driver: Box<dyn Scorer + 'a>, predicates: Vec<DocPredicate<'a>>, must_verifiers: Vec<Box<dyn Scorer + 'a>>, must_not_verifiers: Vec<Box<dyn Scorer + 'a>>, ) -> Self

Trait Implementations

impl DocSet for PredicatedScorer<'_>

fn supports_doc_windows(&self) -> bool

Whether this cursor benefits from bounded score-free membership batches.

fn fill_doc_window(&mut self, base: DocId, bits: &mut DocWindow)

Consume exact matches in [base, base + DOC_WINDOW_SIZE), replacing bits, and leave the cursor on its first match at or after the end. Calls are forward-only; previously consumed documents stay consumed.

fn doc(&self) -> DocId

Current document ID, or TERMINATED if exhausted.

fn advance(&mut self) -> DocId

Advance to the next document. Returns the new doc ID or TERMINATED.

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

Seek to the first document >= target. Returns doc ID or TERMINATED.

fn size_hint(&self) -> u32

Estimated number of remaining documents.

fn supports_doc_batches(&self) -> bool

Whether compact membership batches amortize this cursor’s work.

fn fill_doc_batch(&mut self, docs: &mut DocBatch) -> usize

Consume up to 128 exact sorted matches starting at doc(), leaving the cursor on the first unconsumed match. Zero means exhausted.

fn retain_doc_batch(&mut self, docs: &mut DocBatch, len: usize) -> usize

Retain matches from the sorted unique prefix docs[..len]. The cursor remains at or beyond the last probe; earlier IDs stay consumed.

impl Scorer for PredicatedScorer<'_>

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_windows(&self) -> bool

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

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 score(&self) -> Score

Score for current document

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 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_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 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 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 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).