Struct Searcher 

pub struct Searcher<D: Directory + 'static> { /* private fields */ }

Searcher - provides search over loaded segments

For wasm/read-only use, create via Searcher::open(). For native use with Index, this is created via IndexReader.

Implementations

impl<D: Directory + 'static> Searcher<D>

pub async fn open( directory: Arc<D>, schema: Arc<Schema>, segment_ids: &[String], term_cache_blocks: usize, ) -> Result<Self>

Create a Searcher directly from segment IDs

This is a simpler initialization path that doesn’t require SegmentManager. Use this for read-only access to pre-built indexes.

pub fn schema(&self) -> &Schema

Get the schema

pub fn schema_arc(&self) -> Arc<Schema>

pub fn segment_readers(&self) -> &[Arc<SegmentReader>]

Get segment readers

pub fn default_fields(&self) -> &[Field]

Get default fields for search

pub fn tokenizers(&self) -> &TokenizerRegistry

Get tokenizer registry

pub fn trained_centroids(&self) -> &FxHashMap<u32, Arc<CoarseCentroids>>

Get trained centroids

pub fn trained_binary_quantizers( &self, ) -> &FxHashMap<u32, Arc<BinaryCoarseQuantizer>>

pub fn global_stats(&self) -> &Arc<LazyGlobalStats>

Get lazy global statistics for cross-segment IDF computation

pub fn num_docs(&self) -> u32

Get total document count across all segments

pub fn segment_map(&self) -> &FxHashMap<u128, usize>

Get O(1) segment_id → index map (used by reranker)

pub fn num_segments(&self) -> usize

Get number of segments

pub async fn doc( &self, segment_id: u128, doc_id: u32, ) -> Result<Option<Document>>

Get a document by (segment_id, local_doc_id)

pub async fn search( &self, query: &dyn Query, limit: usize, ) -> Result<Vec<SearchResult>>

Search across all segments and return aggregated results

pub async fn search_with_count( &self, query: &dyn Query, limit: usize, ) -> Result<(Vec<SearchResult>, u32)>

Search across all segments and return (results, total_seen) total_seen is the number of documents that were scored across all segments

pub async fn search_with_offset( &self, query: &dyn Query, limit: usize, offset: usize, ) -> Result<Vec<SearchResult>>

Search with offset for pagination

pub async fn search_with_offset_and_count( &self, query: &dyn Query, limit: usize, offset: usize, ) -> Result<(Vec<SearchResult>, u32)>

Search with offset and return (results, total_seen)

pub async fn search_with_positions( &self, query: &dyn Query, limit: usize, ) -> Result<(Vec<SearchResult>, u32)>

Search with positions (ordinal tracking) and return (results, total_seen)

Use this when you need per-ordinal scores for multi-valued fields.

pub async fn search_with_positions_budgeted( &self, query: &dyn Query, limit: usize, deadline: Option<Instant>, ) -> Result<(Vec<SearchResult>, u32, bool)>

search_with_positions under a wall-clock budget (anytime mode). Returns (results, seen, truncated); truncated is set when an executor stopped scoring at the deadline, in which case the results are the best found so far rather than the exact top-k.

pub async fn search_with_count_budgeted( &self, query: &dyn Query, limit: usize, deadline: Option<Instant>, ) -> Result<(Vec<SearchResult>, u32, bool)>

search_with_count under a wall-clock budget; see Self::search_with_positions_budgeted.

pub async fn search_with_positions_budgeted_stats( &self, query: &dyn Query, limit: usize, deadline: Option<Instant>, stats: Option<Arc<GlobalStats>>, ) -> Result<(Vec<SearchResult>, u32, bool)>

Self::search_with_positions_budgeted with externally supplied text statistics (a broker’s cross-shard document frequencies); they replace the searcher’s own segment-aggregated statistics.

pub async fn search_with_count_budgeted_stats( &self, query: &dyn Query, limit: usize, deadline: Option<Instant>, stats: Option<Arc<GlobalStats>>, ) -> Result<(Vec<SearchResult>, u32, bool)>

Self::search_with_count_budgeted with externally supplied text statistics.

pub fn query_text_stats( &self, query: &dyn Query, stats_override: Option<Arc<GlobalStats>>, ) -> Option<Arc<GlobalStats>>

Text statistics a query scores with: the caller’s override when given, otherwise document frequencies, corpus sizes and average lengths aggregated over every segment of this searcher (None for a single segment, whose local statistics already are the whole).

pub fn search_with_offset_and_count_sync( &self, query: &dyn Query, limit: usize, offset: usize, ) -> Result<(Vec<SearchResult>, u32)>

Synchronous search across all segments using rayon for parallelism.

This is the async-free boundary — no tokio involvement from here down.

pub async fn search_fused( &self, queries: &[(&dyn Query, f32)], fetch_limit: usize, limit: usize, method: FusionMethod, combiner: MultiValueCombiner, ) -> Result<Vec<SearchResult>>

Hybrid search: run several queries independently and fuse their ranked lists (union) into a single top-limit result.

Unlike Self::search_and_rerank — which can only re-score documents the first-stage query already found — fusion keeps documents found by any of the queries. Typical use is sparse (BM25/SPLADE) + dense vector hybrid retrieval with FusionMethod::Rrf { k: 60.0 }.

Fusion happens at chunk granularity: per-ordinal scores are collected from each sub-query, fused per (doc, ordinal) key, then combined into a doc score with combiner (MultiValueCombiner::Max recommended — same-chunk corroboration across verticals compounds, scattered noise does not). Fused results carry per-chunk positions.

Each query is paired with a weight scaling its contribution. fetch_limit is the per-query candidate depth. Request-facing adapters default to at most crate::query::MAX_CANDIDATE_OVERSUBSCRIPTION times the result window and never multiply an existing rerank pool again.

pub async fn search_fused_with_count( &self, queries: &[(&dyn Query, f32)], fetch_limit: usize, limit: usize, method: FusionMethod, combiner: MultiValueCombiner, ) -> Result<(Vec<SearchResult>, u32)>

Fusion variant that also returns the aggregate number of documents scored by all sub-queries. This lets request-facing callers use the parallel fusion path without rerunning sub-queries for observability.

pub fn fuse_candidate_lists( &self, lists: &[(&[SearchResult], f32)], method: FusionMethod, combiner: MultiValueCombiner, limit: usize, ) -> Result<Vec<SearchResult>>

Fuse retained nomination lists on this searcher’s shared CPU pool.

pub fn rrf_scores_for_hits( &self, lists: &[RrfRankedList<'_>], selected: &[(u128, u32)], k: f32, combiner: MultiValueCombiner, ) -> Result<Vec<RrfScore>>

Attribute organic RRF votes without repeating retrieval or changing L1.

pub async fn search_candidate_union( &self, queries: &[Arc<dyn Query>], depth: usize, stats: Arc<GlobalStats>, ) -> Result<(Vec<SearchResult>, u32)>

Retrieve independent branches and retain the complete bounded document union. No rank fusion or cross-branch top-k runs before feature scoring.

pub async fn search_candidate_lists( &self, queries: &[Arc<dyn Query>], depth: usize, stats: Option<Arc<GlobalStats>>, ) -> Result<Vec<(Vec<SearchResult>, u32)>>

Independent nominated lists for coordinator-side global fusion. This uses the same bounded parallel retrieval as candidate backfill.

pub fn merge_candidate_lists<T: Into<SearchResult> + Borrow<SearchResult>>( &self, lists: impl IntoIterator<Item = impl IntoIterator<Item = T>>, ) -> Result<Vec<SearchResult>>

pub async fn search_and_rerank( &self, query: &dyn Query, l1_limit: usize, final_limit: usize, config: &RerankerConfig, ) -> Result<(Vec<SearchResult>, u32)>

Two-stage search: L1 retrieval + L2 dense vector reranking

Runs the query to get l1_limit candidates, then reranks by exact dense vector distance and returns the top final_limit results.

pub async fn query( &self, query_str: &str, limit: usize, ) -> Result<SearchResponse>

Parse query string and search (convenience method)

pub async fn query_offset( &self, query_str: &str, limit: usize, offset: usize, ) -> Result<SearchResponse>

Parse query string and search with offset (convenience method)

pub fn query_parser(&self) -> QueryLanguageParser

Get query parser for this searcher

pub async fn get_document( &self, address: &DocAddress, ) -> Result<Option<Document>>

Get a document by address (segment_id + local doc_id)

pub async fn get_document_with_fields( &self, address: &DocAddress, fields: Option<&FxHashSet<u32>>, ) -> Result<Option<Document>>

Get a document by address, hydrating only the specified field IDs.

If fields is None, all fields are hydrated (including dense vectors). If fields is Some(set), only dense vector fields in the set are read from flat storage — skipping expensive mmap reads for unrequested vectors.

impl<D: Directory + 'static> Searcher<D>

pub async fn candidate_text_stats( &self, plan: &CandidateScoringPlan, ) -> Result<Arc<GlobalStats>>

Complete BM25 statistics over this immutable snapshot, including on native-async and WASM where the synchronous lazy cache is unavailable.

pub async fn score_candidates( &self, candidates: &[SearchResult], plan: &CandidateScoringPlan, stats: Option<Arc<GlobalStats>>, ) -> Result<Vec<ScoredCandidate>>

Score all requested documents against every named branch, including fields which did not nominate them. Addresses must belong to this snapshot; stale addresses and budget overflows fail explicitly.

pub async fn score_candidates_with_retrieved( &self, candidates: &[SearchResult], plan: &CandidateScoringPlan, stats: Option<Arc<GlobalStats>>, retrieved: &[(usize, &[SearchResult])], ) -> Result<Vec<ScoredCandidate>>

Preserve scores from named retrieval branches, then optionally probe only missing logical cells. Branch indices refer to plan.features.

pub async fn score_candidates_with_retrieved_and_rrf( &self, candidates: &[SearchResult], plan: &CandidateScoringPlan, stats: Option<Arc<GlobalStats>>, retrieved: &[(usize, &[SearchResult])], rrf: Option<&[RrfScore]>, ) -> Result<Vec<ScoredCandidate>>

Supply organic RRF features to the same L1 scorer before any top-k.