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, SpanWeight

    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
`protected static class` `Weight.DefaultBulkScorer` Just wraps a Scorer and performs top scoring using it.

### Field Summary

Fields
`protected Query` `parentQuery`

### Constructor Summary

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

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
`BulkScorer` `bulkScorer(LeafReaderContext context)` Optional method, to return a `BulkScorer` to score the query and send hits to a `Collector`.
`abstract Explanation` `explain(LeafReaderContext context, int doc)` An explanation of the score computation for the named document.
`abstract void` `extractTerms(Set<Term> terms)` Deprecated. Use `Query.visit(QueryVisitor)` with `QueryVisitor.termCollector(Set)`
`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 A query match that contains no position information (for example, a Point or DocValues query) will return `MatchesUtils.MATCH_WITH_NO_TERMS`
`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

#### extractTerms

    @Deprecated
    public abstract void extractTerms(Set<Term> terms)

Deprecated. Use `Query.visit(QueryVisitor)` with `QueryVisitor.termCollector(Set)`
Expert: adds all terms occurring in this query to the terms set. If the `Weight` was created with `needsScores == true` then this method will only extract terms which are used for scoring, otherwise it will extract all terms which are used for matching.

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