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

Package org.apache.lucene.misc.search

# Class DiversifiedTopDocsCollector

java.lang.Object
org.apache.lucene.search.TopDocsCollector<DiversifiedTopDocsCollector.ScoreDocKey>
org.apache.lucene.misc.search.DiversifiedTopDocsCollector

All Implemented Interfaces:
  `Collector`

public abstract class DiversifiedTopDocsCollector extends TopDocsCollector<DiversifiedTopDocsCollector.ScoreDocKey>
A `TopDocsCollector` that controls diversity in results by ensuring no more than maxHitsPerKey results from a common source are collected in the final results.

An example application might be a product search in a marketplace where no more than 3 results per retailer are permitted in search results.

To compare behaviour with other forms of collector, a useful analogy might be the problem of making a compilation album of 1967's top hit records:

1. A vanilla query's results might look like a "Best of the Beatles" album - high quality but not much diversity
2. A GroupingSearch would produce the equivalent of "The 10 top-selling artists of 1967 - some killer and quite a lot of filler"
3. A "diversified" query would be the top 20 hit records of that year - with a max of 3 Beatles hits in order to maintain diversity

This collector improves on the "GroupingSearch" type queries by

- Working in one pass over the data
- Not requiring the client to guess how many groups are required
- Removing low-scoring "filler" which sits at the end of each group's hits

This is an abstract class and subclasses have to provide a source of keys for documents which is then used to help identify duplicate sources.

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 class`
  `DiversifiedTopDocsCollector.ScoreDocKey`
  An extension to ScoreDoc that includes a key used for grouping purposes

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected int`
  `maxNumPerKey`

  ### Fields inherited from class org.apache.lucene.search.TopDocsCollector

  `EMPTY_TOPDOCS, pq, totalHits, totalHitsRelation`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DiversifiedTopDocsCollector(int numHits, int maxHitsPerKey)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected abstract NumericDocValues`
  `getKeys(LeafReaderContext context)`
  Get a source of values used for grouping keys
  `LeafCollector`
  `getLeafCollector(LeafReaderContext context)`
  `protected DiversifiedTopDocsCollector.ScoreDocKey`
  `insert(DiversifiedTopDocsCollector.ScoreDocKey addition, int docBase, NumericDocValues keys)`
  `protected TopDocs`
  `newTopDocs(ScoreDoc[] results, int start)`
  `ScoreMode`
  `scoreMode()`

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

  `getTotalHits, populateResults, pruneLeastCompetitiveHitsTo, topDocs, topDocs, topDocs, topDocsSize`

  ### 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

  `setWeight`

- ## Field Details

  - ### maxNumPerKey

    protected int maxNumPerKey

- ## Constructor Details

  - ### DiversifiedTopDocsCollector

    public DiversifiedTopDocsCollector(int numHits, int maxHitsPerKey)

- ## Method Details

  - ### getKeys

    protected abstract NumericDocValues getKeys(LeafReaderContext context)
    Get a source of values used for grouping keys

  - ### scoreMode

    public ScoreMode scoreMode()

  - ### newTopDocs

    protected TopDocs newTopDocs(ScoreDoc[] results, int start)
    Overrides:
      `newTopDocs` in class `TopDocsCollector<DiversifiedTopDocsCollector.ScoreDocKey>`

  - ### insert

    protected DiversifiedTopDocsCollector.ScoreDocKey insert(DiversifiedTopDocsCollector.ScoreDocKey addition, int docBase, NumericDocValues keys) throws IOException
    Throws:
      `IOException`

  - ### getLeafCollector

    public LeafCollector getLeafCollector(LeafReaderContext context) throws IOException
    Throws:
      `IOException`