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
    Modifier and Type | Method and Description
    --- | ---
    `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.

Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.