org.apache.lucene.search

Class DiversifiedTopDocsCollector

java.lang.Object

org.apache.lucene.search.TopDocsCollector<DiversifiedTopDocsCollector.ScoreDocKey>

org.apache.lucene.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DiversifiedTopDocsCollector.ScoreDocKey An extension to ScoreDoc that includes a key used for grouping purposes

Field Summary

Fields

Modifier and Type	Field and Description
protected int	maxNumPerKey

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

EMPTY_TOPDOCS, pq, totalHits

Constructor Summary

Constructors

Constructor and Description
DiversifiedTopDocsCollector(int numHits, int maxHitsPerKey)

Method Summary

Modifier and Type	Method and Description
protected abstract NumericDocValues	getKeys(LeafReaderContext context) Get a source of values used for grouping keys
LeafCollector	getLeafCollector(LeafReaderContext context) Create a new collector to collect the given context.
protected DiversifiedTopDocsCollector.ScoreDocKey	insert(DiversifiedTopDocsCollector.ScoreDocKey addition, int docBase, NumericDocValues keys)
boolean	needsScores() Indicates if document scores are needed by this collector.
protected TopDocs	newTopDocs(ScoreDoc[] results, int start) Returns a TopDocs instance containing the given results.

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

getTotalHits, populateResults, topDocs, topDocs, topDocs, topDocsSize

Methods inherited from class java.lang.Object

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

Field Detail

maxNumPerKey

protected int maxNumPerKey

Constructor Detail

DiversifiedTopDocsCollector

public DiversifiedTopDocsCollector(int numHits,
                                   int maxHitsPerKey)

Method Detail

getKeys

protected abstract NumericDocValues getKeys(LeafReaderContext context)

Get a source of values used for grouping keys

needsScores

public boolean needsScores()

Description copied from interface: Collector

Indicates if document scores are needed by this collector.

Returns:

true if scores are needed.

newTopDocs

protected TopDocs newTopDocs(ScoreDoc[] results,
                             int start)

Description copied from class: TopDocsCollector

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.

Overrides:

newTopDocs in class TopDocsCollector<DiversifiedTopDocsCollector.ScoreDocKey>

insert

protected DiversifiedTopDocsCollector.ScoreDocKey insert(DiversifiedTopDocsCollector.ScoreDocKey addition,
                                                         int docBase,
                                                         NumericDocValues keys)
                                                  throws java.io.IOException

Throws:

java.io.IOException

getLeafCollector

public LeafCollector getLeafCollector(LeafReaderContext context)
                               throws java.io.IOException

Description copied from interface: Collector

Create a new collector to collect the given context.

Parameters:

context - next atomic reader context

Throws:

java.io.IOException