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

Package org.apache.lucene.search

# Class TermScorer

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

public final class TermScorer extends Scorer
Expert: A `Scorer` for documents matching a `Term`.

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

- ## Nested Class Summary

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

  `Scorable.ChildScorable`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TermScorer(ImpactsEnum impactsEnum, Similarity.SimScorer scorer, NumericDocValues norms, boolean topLevelScoringClause)`
  Construct a `TermScorer` that will use impacts to skip blocks of non-competitive documents.
  `TermScorer(PostingsEnum postingsEnum, Similarity.SimScorer scorer, NumericDocValues norms)`
  Construct a `TermScorer` that will iterate all documents.

- ## 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.
  `int`
  `docID()`
  Returns the doc ID that is currently being scored.
  `final int`
  `freq()`
  Returns term frequency in the current document.
  `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.
  `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`.
  `float`
  `score()`
  Returns the score of the current document matching the query.
  `void`
  `setMinCompetitiveScore(float minScore)`
  Optional method: Tell the scorer that its iterator may safely ignore all documents whose score is less than the given `minScore`.
  `float`
  `smoothingScore(int docId)`
  Returns the smoothing score of the current document matching the query.

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

  `twoPhaseIterator`

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

  `getChildren`

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

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

- ## Constructor Details

  - ### TermScorer

    public TermScorer(PostingsEnum postingsEnum, Similarity.SimScorer scorer, NumericDocValues norms)
    Construct a `TermScorer` that will iterate all documents.

  - ### TermScorer

    public TermScorer(ImpactsEnum impactsEnum, Similarity.SimScorer scorer, NumericDocValues norms, boolean topLevelScoringClause)
    Construct a `TermScorer` that will use impacts to skip blocks of non-competitive documents.

- ## Method Details

  - ### docID

    public int docID()
    Description copied from class: `Scorer`
    Returns the doc ID that is currently being scored.
    Specified by:
      `docID` in class `Scorer`

  - ### freq

    public final int freq() throws IOException
    Returns term frequency in the current document.
    Throws:
      `IOException`

  - ### iterator

    public DocIdSetIterator iterator()
    Description copied from class: `Scorer`
    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.

    Specified by:
      `iterator` in class `Scorer`

  - ### score

    public float score() throws IOException
    Description copied from class: `Scorable`
    Returns the score of the current document matching the query.
    Specified by:
      `score` in class `Scorable`
    Throws:
      `IOException`

  - ### smoothingScore

    public float smoothingScore(int docId) throws IOException
    Description copied from class: `Scorable`
    Returns the smoothing score of the current document matching the query. This score is used when the query/term does not appear in the document, and behaves like an idf. The smoothing score is particularly important when the Scorer returns a product of probabilities so that the document score does not go to zero when one probability is zero. This can return 0 or a smoothing score.

    Smoothing scores are described in many papers, including: Metzler, D. and Croft, W. B. , "Combining the Language Model and Inference Network Approaches to Retrieval," Information Processing and Management Special Issue on Bayesian Networks and Information Retrieval, 40(5), pp.735-750.

    Overrides:
      `smoothingScore` in class `Scorable`
    Throws:
      `IOException`

  - ### advanceShallow

    public int advanceShallow(int target) throws IOException
    Description copied from class: `Scorer`
    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 >= `Scorer.docID()` as well as all targets that have been passed to `Scorer.advanceShallow(int)` so far.
    Overrides:
      `advanceShallow` in class `Scorer`
    Throws:
      `IOException`

  - ### getMaxScore

    public float getMaxScore(int upTo) throws IOException
    Description copied from class: `Scorer`
    Return the maximum score that documents between the last `target` that this iterator was `shallow-advanced` to included and `upTo` included.
    Specified by:
      `getMaxScore` in class `Scorer`
    Throws:
      `IOException`

  - ### setMinCompetitiveScore

    public void setMinCompetitiveScore(float minScore)
    Description copied from class: `Scorable`
    Optional method: Tell the scorer that its iterator may safely ignore all documents whose score is less than the given `minScore`. This is a no-op by default.

    This method may only be called from collectors that use `ScoreMode.TOP_SCORES`, and successive calls may only set increasing values of `minScore`.

    Overrides:
      `setMinCompetitiveScore` in class `Scorable`

  - ### nextDocsAndScores

    public void nextDocsAndScores(int upTo, Bits liveDocs, DocAndFloatFeatureBuffer buffer) throws IOException
    Description copied from class: `Scorer`
    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.

    Overrides:
      `nextDocsAndScores` in class `Scorer`
    Throws:
      `IOException`