Class Weight

java.lang.Object
org.apache.lucene.search.Weight
All Implemented Interfaces:
SegmentCacheable
Direct Known Subclasses:
ConstantScoreWeight, DisjunctionMaxQuery.DisjunctionMaxWeight, FilterWeight, IndriAndWeight, PhraseWeight

public abstract class Weight extends Object implements SegmentCacheable
Expert: Calculate query weights and build query scorers.

The purpose of Weight is to ensure searching does not modify a Query, so that a Query instance can be reused.

IndexSearcher dependent state of the query should reside in the Weight.

LeafReader dependent state should reside in the Scorer.

Since Weight creates Scorer instances for a given LeafReaderContext (scorer(org.apache.lucene.index.LeafReaderContext)) callers must maintain the relationship between the searcher's top-level IndexReaderContext and the context used to create a Scorer.

A Weight is used in the following way:

  1. A Weight is constructed by a top-level query, given a IndexSearcher (Query.createWeight(IndexSearcher, ScoreMode, float)).
  2. A Scorer is constructed by scorer(org.apache.lucene.index.LeafReaderContext).
Since:
2.9
  • Field Details

    • parentQuery

      protected final Query parentQuery
  • Constructor Details

    • Weight

      protected Weight(Query query)
      Sole constructor, typically invoked by sub-classes.
      Parameters:
      query - the parent query
  • Method Details

    • matches

      public Matches matches(LeafReaderContext context, int doc) throws IOException
      Returns Matches for a specific document, or null if the document does not match the parent query

      A query match that contains no position information (for example, a Point or DocValues query) will return MatchesUtils.MATCH_WITH_NO_TERMS

      Parameters:
      context - the reader's context to create the Matches for
      doc - the document's id relative to the given context's reader
      Throws:
      IOException
      WARNING: This API is experimental and might change in incompatible ways in the next release.
    • explain

      public abstract Explanation explain(LeafReaderContext context, int doc) throws IOException
      An explanation of the score computation for the named document.
      Parameters:
      context - the readers context to create the Explanation for.
      doc - the document's id relative to the given context's reader
      Returns:
      an Explanation for the score
      Throws:
      IOException - if an IOException occurs
    • getQuery

      public final Query getQuery()
      The query that this concerns.
    • scorer

      public final Scorer scorer(LeafReaderContext context) throws IOException
      Optional method that delegates to scorerSupplier.

      Returns a Scorer which can iterate in order over all matching documents and assign them a score. A scorer for the same LeafReaderContext instance may be requested multiple times as part of a single search call.

      NOTE: null can be returned if no documents will be scored by this query.

      NOTE: The returned Scorer does not have LeafReader.getLiveDocs() applied, they need to be checked on top.

      Parameters:
      context - the LeafReaderContext for which to return the Scorer.
      Returns:
      a Scorer which scores documents in/out-of order.
      Throws:
      IOException - if there is a low-level I/O error
    • scorerSupplier

      public abstract ScorerSupplier scorerSupplier(LeafReaderContext context) throws IOException
      Get a ScorerSupplier, which allows knowing the cost of the Scorer before building it. A scorer supplier for the same LeafReaderContext instance may be requested multiple times as part of a single search call.

      Note: It must return null if the scorer is null.

      Parameters:
      context - the leaf reader context
      Returns:
      a ScorerSupplier providing the scorer, or null if scorer is null
      Throws:
      IOException - if an IOException occurs
      See Also:
    • bulkScorer

      public final BulkScorer bulkScorer(LeafReaderContext context) throws IOException
      Helper method that delegates to scorerSupplier(LeafReaderContext). It is implemented as
       ScorerSupplier scorerSupplier = scorerSupplier(context);
       if (scorerSupplier == null) {
         // No docs match
         return null;
       }
      
       scorerSupplier.setTopLevelScoringClause();
       return scorerSupplier.bulkScorer();
       
      A bulk scorer for the same LeafReaderContext instance may be requested multiple times as part of a single search call.
      Throws:
      IOException
    • count

      public int count(LeafReaderContext context) throws IOException
      Counts the number of live documents that match a given parentQuery in a leaf.

      The default implementation returns -1 for every query. This indicates that the count could not be computed in sub-linear time.

      Specific query classes should override it to provide other accurate sub-linear implementations (that actually return the count). Look at MatchAllDocsQuery.createWeight(IndexSearcher, ScoreMode, float) for an example

      We use this property of the function to count hits in IndexSearcher.count(Query).

      Parameters:
      context - the LeafReaderContext for which to return the count.
      Returns:
      integer count of the number of matches
      Throws:
      IOException - if there is a low-level I/O error