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

Package org.apache.lucene.search.grouping

# Class TopGroups<T>

java.lang.Object
org.apache.lucene.search.grouping.TopGroups<T>

public class TopGroups<T> extends Object
Represents result returned by a grouping search.

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `TopGroups.ScoreMergeMode`
  How the GroupDocs score (if any) should be merged.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final GroupDocs<T>[]`
  `groups`
  Group results in groupSort order
  `final SortField[]`
  `groupSort`
  How groups are sorted against each other
  `final float`
  `maxScore`
  Highest score across all hits, or `Float.NaN` if scores were not computed.
  `final Integer`
  `totalGroupCount`
  The total number of unique groups.
  `final int`
  `totalGroupedHitCount`
  Number of documents grouped into the topN groups
  `final int`
  `totalHitCount`
  Number of documents matching the search
  `final SortField[]`
  `withinGroupSort`
  How docs are sorted within each group

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TopGroups(TopGroups<T> oldTopGroups, Integer totalGroupCount)`
  `TopGroups(SortField[] groupSort, SortField[] withinGroupSort, int totalHitCount, int totalGroupedHitCount, GroupDocs<T>[] groups, float maxScore)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> TopGroups<T>`
  `merge(TopGroups<T>[] shardGroups, Sort groupSort, Sort docSort, int docOffset, int docTopN, TopGroups.ScoreMergeMode scoreMergeMode)`
  Merges an array of TopGroups, for example obtained from the second-pass collector across multiple shards.
  `static <T> TopGroups<T>`
  `mergeBlockGroups(List<TopGroups<T>> shardGroups, Sort groupSort, int groupOffset, int topNGroups, Sort docSort)`
  Merge TopGroups that are partitioned into blocks per shard.

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

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

- ## Field Details

  - ### totalHitCount

    public final int totalHitCount
    Number of documents matching the search

  - ### totalGroupedHitCount

    public final int totalGroupedHitCount
    Number of documents grouped into the topN groups

  - ### totalGroupCount

    public final Integer totalGroupCount
    The total number of unique groups. If `null` this value is not computed.

  - ### groups

    public final GroupDocs<T>[] groups
    Group results in groupSort order

  - ### groupSort

    public final SortField[] groupSort
    How groups are sorted against each other

  - ### withinGroupSort

    public final SortField[] withinGroupSort
    How docs are sorted within each group

  - ### maxScore

    public final float maxScore
    Highest score across all hits, or `Float.NaN` if scores were not computed.

- ## Constructor Details

  - ### TopGroups

    public TopGroups(SortField[] groupSort, SortField[] withinGroupSort, int totalHitCount, int totalGroupedHitCount, GroupDocs<T>[] groups, float maxScore)

  - ### TopGroups

    public TopGroups(TopGroups<T> oldTopGroups, Integer totalGroupCount)

- ## Method Details

  - ### merge

    public static <T> TopGroups<T> merge(TopGroups<T>[] shardGroups, Sort groupSort, Sort docSort, int docOffset, int docTopN, TopGroups.ScoreMergeMode scoreMergeMode)
    Merges an array of TopGroups, for example obtained from the second-pass collector across multiple shards. Each TopGroups must have been sorted by the same groupSort and docSort, and the top groups passed to all second-pass collectors must be the same.

    NOTE: We can't always compute an exact totalGroupCount. Documents belonging to a group may occur on more than one shard and thus the merged totalGroupCount can be higher than the actual totalGroupCount. In this case the totalGroupCount represents a upper bound. If the documents of one group do only reside in one shard then the totalGroupCount is exact.

    NOTE: the topDocs in each GroupDocs is actually an instance of TopDocsAndShards

  - ### mergeBlockGroups

    public static <T> TopGroups<T> mergeBlockGroups(List<TopGroups<T>> shardGroups, Sort groupSort, int groupOffset, int topNGroups, Sort docSort)
    Merge TopGroups that are partitioned into blocks per shard. This method assumes that within each shard, the groups are sorted according to the groupSort.
    Parameters:
      `shardGroups` - list of TopGroups, one per shard.
      `groupSort` - The `Sort` used to sort the groups. The top sorted document within each group according to groupSort, determines how that group sorts against other groups. This must be non-null, ie, if you want to groupSort by relevance use Sort.RELEVANCE.
      `groupOffset` - Which group to start from.
      `topNGroups` - How many top groups to keep.
      `docSort` - The sort to use within each group
    Returns:
      TopGroups instance or null if there are no groups.