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`, `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.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Query` | `parentQuery` |

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `BulkScorer` | `bulkScorer​(LeafReaderContext context)` | Optional method, to return a `BulkScorer` to score the query and send hits to a `Collector`.
    `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.
    `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
    `abstract Scorer` | `scorer​(LeafReaderContext context)` | Returns a `Scorer` which can iterate in order over all matching documents and assign them a score.
    `ScorerSupplier` | `scorerSupplier​(LeafReaderContext context)` | Optional method.

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

    - #### parentQuery

          protected final Query parentQuery

  - ### Constructor Detail

    - #### Weight

          protected Weight​(Query query)

      Sole constructor, typically invoked by sub-classes.
      Parameters:
        `query` - the parent query

  - ### Method Detail

    - #### 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 abstract Scorer scorer​(LeafReaderContext context)
                                 throws IOException

      Returns a `Scorer` which can iterate in order over all matching documents and assign them a score.

      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 ScorerSupplier scorerSupplier​(LeafReaderContext context)
                                        throws IOException

      Optional method. Get a `ScorerSupplier`, which allows to know the cost of the `Scorer` before building it. The default implementation calls `scorer(org.apache.lucene.index.LeafReaderContext)` and builds a `ScorerSupplier` wrapper around it.
      Throws:
        `IOException`
      See Also:
        `scorer(org.apache.lucene.index.LeafReaderContext)`

    - #### bulkScorer

          public BulkScorer bulkScorer​(LeafReaderContext context)
                                throws IOException

      Optional method, to return a `BulkScorer` to score the query and send hits to a `Collector`. Only queries that have a different top-level approach need to override this; the default implementation pulls a normal `Scorer` and iterates and collects the resulting hits which are not marked as deleted.
      Parameters:
        `context` - the `LeafReaderContext` for which to return the `Scorer`.
      Returns:
        a `BulkScorer` which scores documents and passes them to a collector.
      Throws:
        `IOException` - if there is a low-level I/O error

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