Package org.apache.lucene.search

## Class TopKnnCollector

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

- All Implemented Interfaces:
    `KnnCollector`
  Direct Known Subclasses:
    `MultiLeafTopKnnCollector`

      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.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected NeighborQueue` | `queue` |

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

      `visitedCount`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TopKnnCollector​(int k, int visitLimit)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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.
    `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, incVisitedCount, k, visitedCount, visitLimit`

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

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

- - ### Field Detail

    - #### queue

          protected final NeighborQueue queue

  - ### Constructor Detail

    - #### TopKnnCollector

          public TopKnnCollector​(int k,
                                 int visitLimit)

      Parameters:
        `k` - the number of neighbors to collect
        `visitLimit` - how many vector nodes the results are allowed to visit

  - ### Method Detail

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

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`