Trait Query 

pub trait Query:
    Display
    + Send
    + Sync {
    // Required methods
    fn scorer<'a>(
        &self,
        reader: &'a SegmentReader,
        limit: usize,
    ) -> ScorerFuture<'a>;
    fn count_estimate<'a>(&self, reader: &'a SegmentReader) -> CountFuture<'a>;

    // Provided methods
    fn scorer_with_options<'a>(
        &self,
        reader: &'a SegmentReader,
        limit: usize,
        options: ScorerOptions,
    ) -> ScorerFuture<'a> { ... }
    fn scorer_sync<'a>(
        &self,
        reader: &'a SegmentReader,
        limit: usize,
    ) -> Result<Box<dyn Scorer + 'a>> { ... }
    fn scorer_sync_with_options<'a>(
        &self,
        reader: &'a SegmentReader,
        limit: usize,
        options: ScorerOptions,
    ) -> Result<Box<dyn Scorer + 'a>> { ... }
    fn decompose(&self) -> QueryDecomposition { ... }
    fn physical_text_field(
        &self,
        _reader: &SegmentReader,
        _complete: bool,
    ) -> Option<Field> { ... }
    fn sparse_decomposition(&self) -> QueryDecomposition { ... }
    fn candidate_query(&self) -> Result<CandidateQuery> { ... }
    fn text_terms(&self, out: &mut Vec<(Field, Vec<u8>)>) { ... }
    fn is_filter(&self) -> bool { ... }
    fn as_doc_predicate<'a>(
        &self,
        _reader: &'a SegmentReader,
    ) -> Option<DocPredicate<'a>> { ... }
    fn as_doc_bitset(&self, _reader: &SegmentReader) -> Option<DocBitset> { ... }
    fn as_doc_bitset_with_options(
        &self,
        reader: &SegmentReader,
        options: &ScorerOptions,
    ) -> Option<DocBitset> { ... }
    fn bitset_cardinality_estimate(
        &self,
        _reader: &SegmentReader,
    ) -> Option<u64> { ... }
    fn count_equivalent_term(&self) -> Option<TermQueryInfo> { ... }
    fn ranked_count_equivalent_term(&self) -> Option<TermQueryInfo> { ... }
    fn supports_ranked_conjunction_count(&self) -> bool { ... }
    fn should_children(&self) -> Option<&[Arc<dyn Query>]> { ... }
}

A search query (async)

Note: scorer takes &self (not &'a self) so that scorers don’t borrow the query. This enables query composition - queries can create sub-queries locally and get their scorers. Implementations must clone/capture any data they need during scorer creation.

Required Methods

fn scorer<'a>( &self, reader: &'a SegmentReader, limit: usize, ) -> ScorerFuture<'a>

Create a scorer for this query against a single segment (async)

The limit parameter specifies the maximum number of results to return. This is passed from the top-level search limit.

Note: The scorer borrows only the reader, not the query. Implementations should capture any needed query data (field, terms, etc.) during creation.

fn count_estimate<'a>(&self, reader: &'a SegmentReader) -> CountFuture<'a>

Estimated number of matching documents in a segment (async)

Provided Methods

fn scorer_with_options<'a>( &self, reader: &'a SegmentReader, limit: usize, options: ScorerOptions, ) -> ScorerFuture<'a>

Create a scorer with collector-specific construction options. Query implementations that can avoid optional position data should override this; the default preserves existing behavior.

fn scorer_sync<'a>( &self, reader: &'a SegmentReader, limit: usize, ) -> Result<Box<dyn Scorer + 'a>>

Create a scorer synchronously (mmap/RAM only).

Available when the sync feature is enabled. Default implementation returns an error.

fn scorer_sync_with_options<'a>( &self, reader: &'a SegmentReader, limit: usize, options: ScorerOptions, ) -> Result<Box<dyn Scorer + 'a>>

Synchronous counterpart to Query::scorer_with_options.

fn decompose(&self) -> QueryDecomposition

Decompose this query for MaxScore optimization.

Returns TextTerm for simple term queries, SparseTerms for sparse vector queries (single or multi-dim), or Opaque if the query cannot be decomposed.

fn physical_text_field( &self, _reader: &SegmentReader, _complete: bool, ) -> Option<Field>

Opt into one field-local physical address space for collection. Every child must honor the internal scorer scope. Unknown/custom queries retain logical IDs. Ranked term/union executors may keep their existing mapping by opting in only for complete streams.

fn sparse_decomposition(&self) -> QueryDecomposition

Sparse terms for query-global BMP superblock planning only. Unlike scoring decomposition, this never replaces a query’s scorer. A filter wrapper may expose its inner sparse query here while remaining opaque to Boolean scoring optimizations.

fn candidate_query(&self) -> Result<CandidateQuery>

Exact scoring plan for a named L1 branch. Unsupported queries reject explicitly rather than returning truncated retrieval scores.

fn text_terms(&self, out: &mut Vec<(Field, Vec<u8>)>)

Append every (field, term) this query scores with BM25 to out. The searcher aggregates their document frequencies across segments before scoring (see ScorerOptions::global_stats).

fn is_filter(&self) -> bool

True if this query is a pure filter (always scores 1.0, no positions). Used by the planner to convert non-selective MUST filters into predicates.

fn as_doc_predicate<'a>( &self, _reader: &'a SegmentReader, ) -> Option<DocPredicate<'a>>

For filter queries: return a cheap per-doc predicate against a segment. The predicate does O(1) work per doc (e.g., fast-field lookup).

fn as_doc_bitset(&self, _reader: &SegmentReader) -> Option<DocBitset>

Build a compact bitset of matching doc_ids for this query.

Preferred over as_doc_predicate for BMP filtered queries because bitset lookup is ~2ns vs ~30-40ns for a fast-field closure. Default returns None; TermQuery overrides this to build from its posting list in O(M) time.

fn as_doc_bitset_with_options( &self, reader: &SegmentReader, options: &ScorerOptions, ) -> Option<DocBitset>

Budget-aware materialization. None means unsupported or cancelled; cancellation must flag the shared budget, and a partial bitset must never escape as a complete filter.

fn bitset_cardinality_estimate(&self, _reader: &SegmentReader) -> Option<u64>

Cheap estimate of how many docs this filter clause matches in the segment. Used by the boolean planner to order MUST/MUST_NOT evaluation: the narrowest clause is materialized first and wider clauses refine it with per-doc probes instead of being fully materialized. None = unknown (treated as matching everything).

fn count_equivalent_term(&self) -> Option<TermQueryInfo>

A term with identical membership for count-only collection. This does not change scoring decomposition. The collector must still account for deleted rows, chunks and missing metadata.

fn ranked_count_equivalent_term(&self) -> Option<TermQueryInfo>

A term-equivalent cardinality alongside an exact score-only text rank plan. Unlike the count-only hint, opaque/custom plans do not opt in automatically. The collector still validates the indexed document space, deletions, mappings and cardinality gate.

fn supports_ranked_conjunction_count(&self) -> bool

Opt into top-level bounded conjunction results with an exact count. Wrappers must not inherit this automatically: they may consume or hide a child’s cardinality. Defaults to streaming.

fn should_children(&self) -> Option<&[Arc<dyn Query>]>

For a query that is a pure disjunction of sub-queries (a Boolean query with only SHOULD clauses and no boost), the clauses.

The boolean planner flattens these into the enclosing SHOULD list: OR(OR(a, b), c) scores exactly like OR(a, b, c), and the flat form is eligible for MaxScore and filter push-down where the nested form would be an opaque, top-k-truncated sub-scorer.

Trait Implementations

impl Query for Box<dyn Query>

fn as_doc_bitset_with_options( &self, reader: &SegmentReader, options: &ScorerOptions, ) -> Option<DocBitset>

Budget-aware materialization. None means unsupported or cancelled; cancellation must flag the shared budget, and a partial bitset must never escape as a complete filter.

fn scorer<'a>( &self, reader: &'a SegmentReader, limit: usize, ) -> ScorerFuture<'a>

Create a scorer for this query against a single segment (async)

fn count_estimate<'a>(&self, reader: &'a SegmentReader) -> CountFuture<'a>

Estimated number of matching documents in a segment (async)

fn scorer_with_options<'a>( &self, reader: &'a SegmentReader, limit: usize, options: ScorerOptions, ) -> ScorerFuture<'a>

Create a scorer with collector-specific construction options. Query implementations that can avoid optional position data should override this; the default preserves existing behavior.

fn candidate_query(&self) -> Result<CandidateQuery>

Exact scoring plan for a named L1 branch. Unsupported queries reject explicitly rather than returning truncated retrieval scores.

fn text_terms(&self, out: &mut Vec<(Field, Vec<u8>)>)

Append every (field, term) this query scores with BM25 to out. The searcher aggregates their document frequencies across segments before scoring (see ScorerOptions::global_stats).

fn physical_text_field( &self, reader: &SegmentReader, complete: bool, ) -> Option<Field>

Opt into one field-local physical address space for collection. Every child must honor the internal scorer scope. Unknown/custom queries retain logical IDs. Ranked term/union executors may keep their existing mapping by opting in only for complete streams.

fn decompose(&self) -> QueryDecomposition

Decompose this query for MaxScore optimization.

fn sparse_decomposition(&self) -> QueryDecomposition

Sparse terms for query-global BMP superblock planning only. Unlike scoring decomposition, this never replaces a query’s scorer. A filter wrapper may expose its inner sparse query here while remaining opaque to Boolean scoring optimizations.

fn is_filter(&self) -> bool

True if this query is a pure filter (always scores 1.0, no positions). Used by the planner to convert non-selective MUST filters into predicates.

fn as_doc_predicate<'a>( &self, reader: &'a SegmentReader, ) -> Option<DocPredicate<'a>>

For filter queries: return a cheap per-doc predicate against a segment. The predicate does O(1) work per doc (e.g., fast-field lookup).

fn as_doc_bitset(&self, reader: &SegmentReader) -> Option<DocBitset>

Build a compact bitset of matching doc_ids for this query.

fn should_children(&self) -> Option<&[Arc<dyn Query>]>

For a query that is a pure disjunction of sub-queries (a Boolean query with only SHOULD clauses and no boost), the clauses.

fn count_equivalent_term(&self) -> Option<TermQueryInfo>

A term with identical membership for count-only collection. This does not change scoring decomposition. The collector must still account for deleted rows, chunks and missing metadata.

fn ranked_count_equivalent_term(&self) -> Option<TermQueryInfo>

A term-equivalent cardinality alongside an exact score-only text rank plan. Unlike the count-only hint, opaque/custom plans do not opt in automatically. The collector still validates the indexed document space, deletions, mappings and cardinality gate.

fn supports_ranked_conjunction_count(&self) -> bool

Opt into top-level bounded conjunction results with an exact count. Wrappers must not inherit this automatically: they may consume or hide a child’s cardinality. Defaults to streaming.

fn bitset_cardinality_estimate(&self, reader: &SegmentReader) -> Option<u64>

Cheap estimate of how many docs this filter clause matches in the segment. Used by the boolean planner to order MUST/MUST_NOT evaluation: the narrowest clause is materialized first and wider clauses refine it with per-doc probes instead of being fully materialized. None = unknown (treated as matching everything).

fn scorer_sync<'a>( &self, reader: &'a SegmentReader, limit: usize, ) -> Result<Box<dyn Scorer + 'a>>

Create a scorer synchronously (mmap/RAM only).

fn scorer_sync_with_options<'a>( &self, reader: &'a SegmentReader, limit: usize, options: ScorerOptions, ) -> Result<Box<dyn Scorer + 'a>>

Synchronous counterpart to Query::scorer_with_options.

Dyn Compatibility

This trait is dyn compatible.

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

Implementations on Foreign Types

impl Query for Box<dyn Query>

fn as_doc_bitset_with_options( &self, reader: &SegmentReader, options: &ScorerOptions, ) -> Option<DocBitset>

fn scorer<'a>( &self, reader: &'a SegmentReader, limit: usize, ) -> ScorerFuture<'a>

fn count_estimate<'a>(&self, reader: &'a SegmentReader) -> CountFuture<'a>

fn scorer_with_options<'a>( &self, reader: &'a SegmentReader, limit: usize, options: ScorerOptions, ) -> ScorerFuture<'a>

fn candidate_query(&self) -> Result<CandidateQuery>

fn text_terms(&self, out: &mut Vec<(Field, Vec<u8>)>)

fn physical_text_field( &self, reader: &SegmentReader, complete: bool, ) -> Option<Field>

fn decompose(&self) -> QueryDecomposition

fn sparse_decomposition(&self) -> QueryDecomposition

fn is_filter(&self) -> bool

fn as_doc_predicate<'a>( &self, reader: &'a SegmentReader, ) -> Option<DocPredicate<'a>>

fn as_doc_bitset(&self, reader: &SegmentReader) -> Option<DocBitset>

fn should_children(&self) -> Option<&[Arc<dyn Query>]>

fn count_equivalent_term(&self) -> Option<TermQueryInfo>

fn ranked_count_equivalent_term(&self) -> Option<TermQueryInfo>

fn supports_ranked_conjunction_count(&self) -> bool

fn bitset_cardinality_estimate(&self, reader: &SegmentReader) -> Option<u64>

fn scorer_sync<'a>( &self, reader: &'a SegmentReader, limit: usize, ) -> Result<Box<dyn Scorer + 'a>>

fn scorer_sync_with_options<'a>( &self, reader: &'a SegmentReader, limit: usize, options: ScorerOptions, ) -> Result<Box<dyn Scorer + 'a>>

Implementors

impl Query for AllQuery

impl Query for BinaryDenseVectorQuery

impl Query for BooleanQuery

impl Query for BoostQuery

impl Query for DenseVectorQuery

impl Query for FilteredQuery

impl Query for PhraseQuery

impl Query for PrefixQuery

impl Query for RangeQuery

impl Query for RegexQuery

impl Query for SparseTermQuery

impl Query for SparseVectorQuery

impl Query for TermQuery

impl Query for WildcardQuery