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