Package org.apache.lucene.search

# Class TopDocs

java.lang.Object
org.apache.lucene.search.TopDocs

Direct Known Subclasses:
  `TopFieldDocs`

public class TopDocs extends Object
Represents hits returned by `IndexSearcher.search(Query,int)`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `ScoreDoc[]`
  `scoreDocs`
  The top hits for the query.
  `TotalHits`
  `totalHits`
  The total number of hits for the query.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TopDocs(TotalHits totalHits, ScoreDoc[] scoreDocs)`
  Constructs a TopDocs.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static TopDocs`
  `merge(int start, int topN, TopDocs[] shardHits)`
  Same as `merge(int, TopDocs[])` but also ignores the top `start` top docs.
  `static TopDocs`
  `merge(int start, int topN, TopDocs[] shardHits, Comparator<ScoreDoc> tieBreaker)`
  Same as above, but accepts the passed in tie breaker
  `static TopDocs`
  `merge(int topN, TopDocs[] shardHits)`
  Returns a new TopDocs, containing topN results across the provided TopDocs, sorting by score.
  `static TopFieldDocs`
  `merge(Sort sort, int start, int topN, TopFieldDocs[] shardHits)`
  Same as `merge(Sort, int, TopFieldDocs[])` but also ignores the top `start` top docs.
  `static TopFieldDocs`
  `merge(Sort sort, int start, int topN, TopFieldDocs[] shardHits, Comparator<ScoreDoc> tieBreaker)`
  Pass in a custom tie breaker for ordering results
  `static TopFieldDocs`
  `merge(Sort sort, int topN, TopFieldDocs[] shardHits)`
  Returns a new TopFieldDocs, containing topN results across the provided TopFieldDocs, sorting by the specified `Sort`.
  `static TopDocs`
  `rrf(int topN, int k, TopDocs[] hits)`
  Reciprocal Rank Fusion method.

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

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

- ## Field Details

  - ### totalHits

    public TotalHits totalHits
    The total number of hits for the query.

  - ### scoreDocs

    public ScoreDoc[] scoreDocs
    The top hits for the query.

- ## Constructor Details

  - ### TopDocs

    public TopDocs(TotalHits totalHits, ScoreDoc[] scoreDocs)
    Constructs a TopDocs.

- ## Method Details

  - ### merge

    public static TopDocs merge(int topN, TopDocs[] shardHits)
    Returns a new TopDocs, containing topN results across the provided TopDocs, sorting by score. Each `TopDocs` instance must be sorted.
    See Also:
      - `merge(int, int, TopDocs[])`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### merge

    public static TopDocs merge(int start, int topN, TopDocs[] shardHits)
    Same as `merge(int, TopDocs[])` but also ignores the top `start` top docs. This is typically useful for pagination.

    docIDs are expected to be in consistent pattern i.e. either all ScoreDocs have their shardIndex set, or all have them as -1 (signifying that all hits belong to same searcher)

    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### merge

    public static TopDocs merge(int start, int topN, TopDocs[] shardHits, Comparator<ScoreDoc> tieBreaker)
    Same as above, but accepts the passed in tie breaker

    docIDs are expected to be in consistent pattern i.e. either all ScoreDocs have their shardIndex set, or all have them as -1 (signifying that all hits belong to same searcher)

    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### merge

    public static TopFieldDocs merge(Sort sort, int topN, TopFieldDocs[] shardHits)
    Returns a new TopFieldDocs, containing topN results across the provided TopFieldDocs, sorting by the specified `Sort`. Each of the TopDocs must have been sorted by the same Sort, and sort field values must have been filled.
    See Also:
      - `merge(Sort, int, int, TopFieldDocs[])`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### merge

    public static TopFieldDocs merge(Sort sort, int start, int topN, TopFieldDocs[] shardHits)
    Same as `merge(Sort, int, TopFieldDocs[])` but also ignores the top `start` top docs. This is typically useful for pagination.

    docIDs are expected to be in consistent pattern i.e. either all ScoreDocs have their shardIndex set, or all have them as -1 (signifying that all hits belong to same searcher)

    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### merge

    public static TopFieldDocs merge(Sort sort, int start, int topN, TopFieldDocs[] shardHits, Comparator<ScoreDoc> tieBreaker)
    Pass in a custom tie breaker for ordering results
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### rrf

    public static TopDocs rrf(int topN, int k, TopDocs[] hits)
    Reciprocal Rank Fusion method.

    This method combines different search results into a single ranked list by combining their ranks. This is especially well suited when combining hits computed via different methods, whose score distributions are hardly comparable.

    Parameters:
      `topN` - the top N results to be returned
      `k` - a constant determines how much influence documents in individual rankings have on the final result. A higher value gives lower rank documents more influence. k should be greater than or equal to 1.
      `hits` - a list of TopDocs to apply RRF on
    Returns:
      a TopDocs contains the top N ranked results.