org.apache.lucene.search

## Class Weight

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

Direct Known Subclasses:
  BooleanQuery.BooleanWeight, ConstantScoreQuery.ConstantWeight, DisjunctionMaxQuery.DisjunctionMaxWeight, SpanWeight

    public abstract class Weight
    extends Object

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`.
`AtomicReader` dependent state should reside in the `Scorer`.

Since `Weight` creates `Scorer` instances for a given `AtomicReaderContext` (`scorer(AtomicReaderContext, boolean, boolean, Bits)`) 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)`).
2. The `getValueForNormalization()` method is called on the `Weight` to compute the query normalization factor `Similarity.queryNorm(float)` of the query clauses contained in the query.
3. The query normalization factor is passed to `normalize(float, float)`. At this point the weighting is complete.
4. A `Scorer` is constructed by `scorer(AtomicReaderContext, boolean, boolean, Bits)`.

Since:
  2.9

### Constructor Summary

Constructors
Constructor and Description
`Weight()`

### Method Summary

Methods
`abstract Explanation` `explain(AtomicReaderContext context, int doc)` An explanation of the score computation for the named document.
`abstract Query` `getQuery()` The query that this concerns.
`abstract float` `getValueForNormalization()` The value for normalization of contained query clauses (e.g.
`abstract void` `normalize(float norm, float topLevelBoost)` Assigns the query normalization factor and boost from parent queries to this.
`abstract Scorer` `scorer(AtomicReaderContext context, boolean scoreDocsInOrder, boolean topScorer, Bits acceptDocs)` Returns a `Scorer` which scores documents in/out-of order according to `scoreDocsInOrder`.
`boolean` `scoresDocsOutOfOrder()` Returns true iff this implementation scores docs only out of order.

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

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

### Constructor Detail

#### Weight

    public Weight()

### Method Detail

#### explain

    public abstract Explanation explain(AtomicReaderContext 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 abstract Query getQuery()

The query that this concerns.

#### getValueForNormalization

    public abstract float getValueForNormalization()
                                            throws IOException

The value for normalization of contained query clauses (e.g. sum of squared weights).

Throws:
  `IOException`

#### normalize

    public abstract void normalize(float norm,
                 float topLevelBoost)

Assigns the query normalization factor and boost from parent queries to this.

#### scorer

    public abstract Scorer scorer(AtomicReaderContext context,
                boolean scoreDocsInOrder,
                boolean topScorer,
                Bits acceptDocs)
                           throws IOException

Returns a `Scorer` which scores documents in/out-of order according to `scoreDocsInOrder`.

NOTE: even if `scoreDocsInOrder` is false, it is recommended to check whether the returned `Scorer` indeed scores documents out of order (i.e., call `scoresDocsOutOfOrder()`), as some `Scorer` implementations will always return documents in-order.
NOTE: null can be returned if no documents will be scored by this query.

Parameters:
  `context` - the `AtomicReaderContext` for which to return the `Scorer`.
  `scoreDocsInOrder` - specifies whether in-order scoring of documents is required. Note that if set to false (i.e., out-of-order scoring is required), this method can return whatever scoring mode it supports, as every in-order scorer is also an out-of-order one. However, an out-of-order scorer may not support `DocIdSetIterator.nextDoc()` and/or `DocIdSetIterator.advance(int)`, therefore it is recommended to request an in-order scorer if use of these methods is required.
  `topScorer` - if true, `Scorer.score(Collector)` will be called; if false, `DocIdSetIterator.nextDoc()` and/or `DocIdSetIterator.advance(int)` will be called.
  `acceptDocs` - Bits that represent the allowable docs to match (typically deleted docs but possibly filtering other documents)
Returns:
  a `Scorer` which scores documents in/out-of order.
Throws:
  `IOException` - if there is a low-level I/O error

#### scoresDocsOutOfOrder

    public boolean scoresDocsOutOfOrder()

Returns true iff this implementation scores docs only out of order. This method is used in conjunction with `Collector`'s `acceptsDocsOutOfOrder` and `scorer(AtomicReaderContext, boolean, boolean, Bits)` to create a matching `Scorer` instance for a given `Collector`, or vice versa.

NOTE: the default implementation returns `false`, i.e. the `Scorer` scores documents in-order.