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

Package org.apache.lucene.search

# Class TopDocsCollector<T extends ScoreDoc>

java.lang.Object
org.apache.lucene.search.TopDocsCollector<T>

All Implemented Interfaces:
  `Collector`

Direct Known Subclasses:
  `TopFieldCollector`, `TopScoreDocCollector`

public abstract class TopDocsCollector<T extends ScoreDoc> extends Object implements Collector
A base class for all collectors that return a `TopDocs` output. This collector allows easy extension by providing a single constructor which accepts a `PriorityQueue` as well as protected members for that priority queue and a counter of the number of total hits.
Extending classes can override any of the methods to provide their own implementation, as well as avoid the use of the priority queue entirely by passing null to `TopDocsCollector(PriorityQueue)`. In that case however, you might want to consider overriding all methods, in order to avoid a NullPointerException.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final TopDocs`
  `EMPTY_TOPDOCS`
  This is used in case topDocs() is called with illegal parameters, or there simply aren't (enough) results.
  `protected final PriorityQueue<T>`
  `pq`
  The priority queue which holds the top documents.
  `protected int`
  `totalHits`
  The total number of documents that the collector encountered.
  `protected TotalHits.Relation`
  `totalHitsRelation`
  Whether `totalHits` is exact or a lower bound.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `TopDocsCollector(PriorityQueue<T> pq)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getTotalHits()`
  The total number of documents that matched this query.
  `protected TopDocs`
  `newTopDocs(ScoreDoc[] results, int start)`
  Returns a `TopDocs` instance containing the given results.
  `protected void`
  `populateResults(ScoreDoc[] results, int howMany)`
  Populates the results array with the ScoreDoc instances.
  `protected void`
  `pruneLeastCompetitiveHitsTo(int keep)`
  Prune the least competitive hits until the number of candidates is less than or equal to `keep`.
  `TopDocs`
  `topDocs()`
  Returns the top docs that were collected by this collector.
  `TopDocs`
  `topDocs(int start)`
  Returns the documents in the range [start ..
  `TopDocs`
  `topDocs(int start, int howMany)`
  Returns the documents in the range [start ..
  `protected int`
  `topDocsSize()`
  The number of valid PQ entries

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

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

  ### Methods inherited from interface org.apache.lucene.search.Collector

  `getLeafCollector, scoreMode, setWeight`

- ## Field Details

  - ### EMPTY_TOPDOCS

    public static final TopDocs EMPTY_TOPDOCS
    This is used in case topDocs() is called with illegal parameters, or there simply aren't (enough) results.
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### pq

    protected final PriorityQueue<T extends ScoreDoc> pq
    The priority queue which holds the top documents. Note that different implementations of PriorityQueue give different meaning to 'top documents'. HitQueue for example aggregates the top scoring documents, while other PQ implementations may hold documents sorted by other criteria.

  - ### totalHits

    protected int totalHits
    The total number of documents that the collector encountered.

  - ### totalHitsRelation

    protected TotalHits.Relation totalHitsRelation
    Whether `totalHits` is exact or a lower bound.

- ## Constructor Details

  - ### TopDocsCollector

    protected TopDocsCollector(PriorityQueue<T> pq)

- ## Method Details

  - ### populateResults

    protected void populateResults(ScoreDoc[] results, int howMany)
    Populates the results array with the ScoreDoc instances. This can be overridden in case a different ScoreDoc type should be returned.

  - ### newTopDocs

    protected TopDocs newTopDocs(ScoreDoc[] results, int start)
    Returns a `TopDocs` instance containing the given results. If `results` is null it means there are no results to return, either because there were 0 calls to collect() or because the arguments to topDocs were invalid.

  - ### getTotalHits

    public int getTotalHits()
    The total number of documents that matched this query.

  - ### topDocsSize

    protected int topDocsSize()
    The number of valid PQ entries

  - ### topDocs

    public TopDocs topDocs()
    Returns the top docs that were collected by this collector.

  - ### topDocs

    public TopDocs topDocs(int start)
    Returns the documents in the range [start .. pq.size()) that were collected by this collector. Note that if `start >= pq.size()`, an empty TopDocs is returned.
    This method is convenient to call if the application always asks for the last results, starting from the last 'page'.
    NOTE: you cannot call this method more than once for each search execution. If you need to call it more than once, passing each time a different `start`, you should call `topDocs()` and work with the returned `TopDocs` object, which will contain all the results this search execution collected.

  - ### topDocs

    public TopDocs topDocs(int start, int howMany)
    Returns the documents in the range [start .. start+howMany) that were collected by this collector. Note that if `start >= pq.size()`, an empty TopDocs is returned, and if pq.size() - start < howMany, then only the available documents in [start .. pq.size()) are returned.
    This method is useful to call in case pagination of search results is allowed by the search application, as well as it attempts to optimize the memory used by allocating only as much as requested by howMany.
    NOTE: you cannot call this method more than once for each search execution. If you need to call it more than once, passing each time a different range, you should call `topDocs()` and work with the returned `TopDocs` object, which will contain all the results this search execution collected.

  - ### pruneLeastCompetitiveHitsTo

    protected void pruneLeastCompetitiveHitsTo(int keep)
    Prune the least competitive hits until the number of candidates is less than or equal to `keep`. This is typically called before `populateResults(org.apache.lucene.search.ScoreDoc[], int)` to ensure we are at right pos.