Weight (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.search, class: Weight

Package org.apache.lucene.search

# Class Weight

java.lang.Object
org.apache.lucene.search.Weight

All Implemented Interfaces:
  `SegmentCacheable`

Direct Known Subclasses:
  `ConstantScoreWeight`, `DisjunctionMaxQuery.DisjunctionMaxWeight`, `FilterWeight`, `IndriAndWeight`, `LogOddsFusionQuery.LogOddsFusionWeight`, `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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `Weight.DefaultBulkScorer`
  Just wraps a Scorer and performs top scoring using it.
  `protected static final class`
  `Weight.DefaultScorerSupplier`
  A wrap for default scorer supplier.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Query`
  `parentQuery`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Weight(Query query)`
  Sole constructor, typically invoked by sub-classes.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final BulkScorer`
  `bulkScorer(LeafReaderContext context)`
  Helper method that delegates to `scorerSupplier(LeafReaderContext)`.
  `int`
  `count(LeafReaderContext context)`
  Counts the number of live documents that match a given `parentQuery` in a leaf.
  `abstract Explanation`
  `explain(LeafReaderContext context, int doc)`
  An explanation of the score computation for the named document.
  `final Query`
  `getQuery()`
  The query that this concerns.
  `Matches`
  `matches(LeafReaderContext context, int doc)`
  Returns `Matches` for a specific document, or `null` if the document does not match the parent query
  `final Scorer`
  `scorer(LeafReaderContext context)`
  Optional method that delegates to scorerSupplier.
  `abstract ScorerSupplier`
  `scorerSupplier(LeafReaderContext context)`
  Get a `ScorerSupplier`, which allows knowing the cost of the `Scorer` before building it.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.apache.lucene.search.SegmentCacheable

  `isCacheable`

- ## 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:
      - `Scorer`
      - `Weight.DefaultScorerSupplier`

  - ### 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