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.

  • 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 Scorers 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.