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

Package org.apache.lucene.search

# Class TopKnnCollector

java.lang.Object
org.apache.lucene.search.AbstractKnnCollector
org.apache.lucene.search.TopKnnCollector

All Implemented Interfaces:
  `KnnCollector`

public class TopKnnCollector extends AbstractKnnCollector
TopKnnCollector is a specific KnnCollector. A minHeap is used to keep track of the currently collected vectors allowing for efficient updates as better vectors are collected.

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

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface org.apache.lucene.search.KnnCollector

  `KnnCollector.Decorator`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final NeighborQueue`
  `queue`

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

  `visitedCount`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TopKnnCollector(int k, int visitLimit)`
  Constructor, with default search strategy
  `TopKnnCollector(int k, int visitLimit, KnnSearchStrategy searchStrategy)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `collect(int docId, float similarity)`
  Collect the provided docId and include in the result set.
  `float`
  `minCompetitiveSimilarity()`
  This method is utilized during search to ensure only competitive results are explored.
  `int`
  `numCollected()`
  `TopDocs`
  `topDocs()`
  This drains the collected nearest kNN results and returns them in a new `TopDocs` collection, ordered by score descending.
  `String`
  `toString()`

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

  `earlyTerminated, getSearchStrategy, incVisitedCount, k, visitedCount, visitLimit`

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

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

- ## Field Details

  - ### queue

    protected final NeighborQueue queue

- ## Constructor Details

  - ### TopKnnCollector

    public TopKnnCollector(int k, int visitLimit)
    Constructor, with default search strategy

  - ### TopKnnCollector

    public TopKnnCollector(int k, int visitLimit, KnnSearchStrategy searchStrategy)
    Parameters:
      `k` - the number of neighbors to collect
      `visitLimit` - how many vector nodes the results are allowed to visit
      `searchStrategy` - the search strategy to use

- ## Method Details

  - ### 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`
    Specified by:
      `collect` in class `AbstractKnnCollector`
    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`
    Specified by:
      `minCompetitiveSimilarity` in class `AbstractKnnCollector`
    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`
    Specified by:
      `topDocs` in class `AbstractKnnCollector`
    Returns:
      The collected top documents

  - ### numCollected

    public int numCollected()
    Specified by:
      `numCollected` in class `AbstractKnnCollector`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`