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

Package org.apache.lucene.search

# Class HnswQueueSaturationCollector

java.lang.Object
org.apache.lucene.search.KnnCollector.Decorator
org.apache.lucene.search.HnswQueueSaturationCollector

All Implemented Interfaces:
  `KnnCollector`

public class HnswQueueSaturationCollector extends KnnCollector.Decorator
A `KnnCollector.Decorator` that early exits when nearest neighbor queue keeps saturating beyond a 'patience' parameter. This records the rate of collection of new nearest neighbors in the `delegate` KnnCollector queue, at each HNSW node candidate visit. Once it saturates for a number of consecutive node visits (e.g., the patience parameter), this early terminates.

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 inherited from class org.apache.lucene.search.KnnCollector.Decorator

  `collector`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HnswQueueSaturationCollector(KnnCollector delegate, double saturationThreshold, int patience)`

- ## 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`
  `nextCandidate()`
  `TopDocs`
  `topDocs()`
  This drains the collected nearest kNN results and returns them in a new `TopDocs` collection, ordered by score descending.

  ### Methods inherited from class org.apache.lucene.search.KnnCollector.Decorator

  `incVisitedCount, k, minCompetitiveSimilarity, visitedCount, visitLimit`

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

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

- ## Constructor Details

  - ### HnswQueueSaturationCollector

    public HnswQueueSaturationCollector(KnnCollector delegate, double saturationThreshold, int patience)

- ## Method Details

  - ### 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`
    Overrides:
      `earlyTerminated` in class `KnnCollector.Decorator`
    Returns:
      is the current result set marked as incomplete?

  - ### 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`
    Overrides:
      `collect` in class `KnnCollector.Decorator`
    Parameters:
      `docId` - of the vector to collect
      `similarity` - its calculated similarity
    Returns:
      true if the vector is collected

  - ### 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`
    Overrides:
      `topDocs` in class `KnnCollector.Decorator`
    Returns:
      The collected top documents

  - ### nextCandidate

    public void nextCandidate()

  - ### getSearchStrategy

    public KnnSearchStrategy getSearchStrategy()
    Specified by:
      `getSearchStrategy` in interface `KnnCollector`
    Overrides:
      `getSearchStrategy` in class `KnnCollector.Decorator`
    Returns:
      the search strategy used by this collector, can be null