Package org.apache.lucene.search.knn

Class MultiLeafKnnCollector

java.lang.Object

org.apache.lucene.search.knn.MultiLeafKnnCollector

All Implemented Interfaces:

KnnCollector

public final class MultiLeafKnnCollector
extends Object
implements KnnCollector

MultiLeafKnnCollector is a specific KnnCollector that can exchange the top collected results across segments through a shared global queue.

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

Constructor Summary

Constructors

Constructor	Description
MultiLeafKnnCollector(int k, BlockingFloatHeap globalSimilarityQueue, AbstractKnnCollector subCollector)	Create a new MultiLeafKnnCollector.

Method Summary

Modifier and Type	Method	Description
boolean	collect(int docId, float similarity)	Collect the provided docId and include in the result set.
boolean	earlyTerminated()	If search visits too many documents, the results collector will terminate early.
void	incVisitedCount(int count)
int	k()
float	minCompetitiveSimilarity()	This method is utilized during search to ensure only competitive results are explored.
TopDocs	topDocs()	This drains the collected nearest kNN results and returns them in a new TopDocs collection, ordered by score descending.
String	toString()
long	visitedCount()
long	visitLimit()

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiLeafKnnCollector

public MultiLeafKnnCollector(int k,
                             BlockingFloatHeap globalSimilarityQueue,
                             AbstractKnnCollector subCollector)

Create a new MultiLeafKnnCollector.

Parameters:

k - the number of neighbors to collect

globalSimilarityQueue - the global queue of the highest similarities collected so far across all segments

subCollector - the local collector

Method Detail

earlyTerminated

public boolean earlyTerminated()

Description copied from interface: KnnCollector

If search visits too many documents, the results collector will terminate early. Usually, this is due to some restricted filter on the document set.

When collection is earlyTerminated, the results are not a correct representation of k nearest neighbors.

Specified by:

earlyTerminated in interface KnnCollector

Returns:

is the current result set marked as incomplete?

incVisitedCount

public void incVisitedCount(int count)

Specified by:

incVisitedCount in interface KnnCollector

Parameters:

count - increments the visited vector count, must be greater than 0.

visitedCount

public long visitedCount()

Specified by:

visitedCount in interface KnnCollector

Returns:

the current visited vector count

visitLimit

public long visitLimit()

Specified by:

visitLimit in interface KnnCollector

Returns:

the visited vector limit

k

public int k()

Specified by:

k in interface KnnCollector

Returns:

the expected number of collected results

collect

public boolean collect(int docId,
                       float similarity)

Description copied from interface: KnnCollector

Collect the provided docId and include in the result set.

Specified by:

collect in interface KnnCollector

Parameters:

docId - of the vector to collect

similarity - its calculated similarity

Returns:

true if the vector is collected

minCompetitiveSimilarity

public float minCompetitiveSimilarity()

Description copied from interface: KnnCollector

This method is utilized during search to ensure only competitive results are explored.

Consequently, if this results collector wants to collect `k` results, this should return Float.NEGATIVE_INFINITY when not full.

When full, the minimum score should be returned.

Specified by:

minCompetitiveSimilarity in interface KnnCollector

Returns:

the current minimum competitive similarity in the collection

topDocs

public TopDocs topDocs()

Description copied from interface: KnnCollector

This drains the collected nearest kNN results and returns them in a new TopDocs collection, ordered by score descending. NOTE: This is generally a destructive action and the collector should not be used after topDocs() is called.

Specified by:

topDocs in interface KnnCollector

Returns:

The collected top documents

toString

public String toString()

Overrides:

toString in class Object