Scorer (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.search, class: Scorer

Package org.apache.lucene.search

# Class Scorer

java.lang.Object
org.apache.lucene.search.Scorable
org.apache.lucene.search.Scorer

Direct Known Subclasses:
  `ConstantScoreScorer`, `FilterScorer`, `IndriScorer`, `TermScorer`

public abstract class Scorer extends Scorable
Expert: Common scoring functionality for different types of queries.

A `Scorer` exposes an `iterator()` over documents matching a query in increasing order of doc id.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.search.Scorable

  `Scorable.ChildScorable`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Scorer()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `advanceShallow(int target)`
  Advance to the block of documents that contains `target` in order to get scoring information about this block.
  `abstract int`
  `docID()`
  Returns the doc ID that is currently being scored.
  `abstract float`
  `getMaxScore(int upTo)`
  Return the maximum score that documents between the last `target` that this iterator was `shallow-advanced` to included and `upTo` included.
  `abstract DocIdSetIterator`
  `iterator()`
  Return a `DocIdSetIterator` over matching documents.
  `void`
  `nextDocsAndScores(int upTo, Bits liveDocs, DocAndFloatFeatureBuffer buffer)`
  Return a new batch of doc IDs and scores, starting at the current doc ID, and ending before `upTo`.
  `TwoPhaseIterator`
  `twoPhaseIterator()`
  Optional method: Return a `TwoPhaseIterator` view of this `Scorer`.

  ### Methods inherited from class org.apache.lucene.search.Scorable

  `getChildren, score, setMinCompetitiveScore, smoothingScore`

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

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

- ## Constructor Details

  - ### Scorer

    public Scorer()

- ## Method Details

  - ### docID

    public abstract int docID()
    Returns the doc ID that is currently being scored.

  - ### iterator

    public abstract DocIdSetIterator iterator()
    Return a `DocIdSetIterator` over matching documents.

    The returned iterator will either be positioned on `-1` if no documents have been scored yet, `DocIdSetIterator.NO_MORE_DOCS` if all documents have been scored already, or the last document id that has been scored otherwise.

    The returned iterator is a view: calling this method several times will return iterators that have the same state.

  - ### twoPhaseIterator

    public TwoPhaseIterator twoPhaseIterator()
    Optional method: Return a `TwoPhaseIterator` view of this `Scorer`. A return value of `null` indicates that two-phase iteration is not supported.

    Note that the returned `TwoPhaseIterator`'s `approximation` must advance synchronously with the `iterator()`: advancing the approximation must advance the iterator and vice-versa.

    Implementing this method is typically useful on `Scorer`s that have a high per-document overhead in order to confirm matches.

    The default implementation returns `null`.

  - ### advanceShallow

    public int advanceShallow(int target) throws IOException
    Advance to the block of documents that contains `target` in order to get scoring information about this block. This method is implicitly called by `DocIdSetIterator.advance(int)` and `DocIdSetIterator.nextDoc()` on the returned doc ID. Calling this method doesn't modify the current `DocIdSetIterator.docID()`. It returns a number that is greater than or equal to all documents contained in the current block, but less than any doc IDS of the next block. `target` must be >= `docID()` as well as all targets that have been passed to `advanceShallow(int)` so far.
    Throws:
      `IOException`

  - ### getMaxScore

    public abstract float getMaxScore(int upTo) throws IOException
    Return the maximum score that documents between the last `target` that this iterator was `shallow-advanced` to included and `upTo` included.
    Throws:
      `IOException`

  - ### nextDocsAndScores

    public void nextDocsAndScores(int upTo, Bits liveDocs, DocAndFloatFeatureBuffer buffer) throws IOException
    Return a new batch of doc IDs and scores, starting at the current doc ID, and ending before `upTo`. Because it starts on the current doc ID, it is illegal to call this method if the `current doc ID` is `-1`.

    An empty return value indicates that there are no postings left between the current doc ID and `upTo`.

    Implementations should ideally fill the buffer with a number of entries comprised between 8 and a couple hundreds, to keep heap requirements contained, while still being large enough to enable operations on the buffer to auto-vectorize efficiently.

    The default implementation is provided below:

         int batchSize = 64; // arbitrary
         buffer.growNoCopy(batchSize);
         int size = 0;
         DocIdSetIterator iterator = iterator();
         for (int doc = docID(); doc < upTo && size < batchSize; doc = iterator.nextDoc()) {
           if (liveDocs == null || liveDocs.get(doc)) {
             buffer.docs[size] = doc;
             buffer.scores[size] = score();
             ++size;
           }
         }
         buffer.size = size;

    NOTE: The provided `DocAndFloatFeatureBuffer` should not hold references to internal data structures.

    NOTE: In case this `Scorer` exposes a `TwoPhaseIterator`, it should be positioned on a matching document before this method is called.

    Throws:
      `IOException`
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.