KnnCollector (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.search, interface: KnnCollector

Package org.apache.lucene.search

# Interface KnnCollector

All Known Implementing Classes:
  `AbstractKnnCollector`, `HnswGraphBuilder.GraphBuilderKnnCollector`, `HnswQueueSaturationCollector`, `KnnCollector.Decorator`, `MultiLeafKnnCollector`, `OrdinalTranslatedKnnCollector`, `TopKnnCollector`

public interface KnnCollector
KnnCollector is a knn collector used for gathering kNN results and providing topDocs from the gathered neighbors

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `KnnCollector.Decorator`
  KnnCollector.Decorator is the base class for decorators of KnnCollector objects, which extend the object with new behaviors.

- ## 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.
  `KnnSearchStrategy`
  `getSearchStrategy()`
  `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.
  `long`
  `visitedCount()`
  `long`
  `visitLimit()`

- ## Method Details

  - ### earlyTerminated

    boolean earlyTerminated()
    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.

    Returns:
      is the current result set marked as incomplete?

  - ### incVisitedCount

    void incVisitedCount(int count)
    Parameters:
      `count` - increments the visited vector count, must be greater than 0.

  - ### visitedCount

    long visitedCount()
    Returns:
      the current visited vector count

  - ### visitLimit

    long visitLimit()
    Returns:
      the visited vector limit

  - ### k

    int k()
    Returns:
      the expected number of collected results

  - ### collect

    boolean collect(int docId, float similarity)
    Collect the provided docId and include in the result set.
    Parameters:
      `docId` - of the vector to collect
      `similarity` - its calculated similarity
    Returns:
      true if the vector is collected

  - ### minCompetitiveSimilarity

    float minCompetitiveSimilarity()
    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.

    Returns:
      the current minimum competitive similarity in the collection

  - ### topDocs

    TopDocs topDocs()
    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.
    Returns:
      The collected top documents

  - ### getSearchStrategy

    KnnSearchStrategy getSearchStrategy()
    Returns:
      the search strategy used by this collector, can be null