HnswGraphSearcher (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.util.hnsw, class: HnswGraphSearcher

Package org.apache.lucene.util.hnsw

# Class HnswGraphSearcher

java.lang.Object
org.apache.lucene.util.hnsw.HnswGraphSearcher

Direct Known Subclasses:
  `FilteredHnswGraphSearcher`

public class HnswGraphSearcher extends Object
Searches an HNSW graph to find nearest neighbors to a query vector. For more background on the search algorithm, see `HnswGraph`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected int[]`
  `bulkNodes`
  `protected float[]`
  `bulkScores`
  `protected final NeighborQueue`
  `candidates`
  Scratch data structures that are used in each `searchLevel(org.apache.lucene.util.hnsw.RandomVectorScorer, int, int, int[], org.apache.lucene.util.hnsw.HnswGraph)` call.
  `protected BitSet`
  `visited`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HnswGraphSearcher(NeighborQueue candidates, BitSet visited)`
  Creates a new graph searcher.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `expectedVisitedNodes(int k, int graphSize)`
  HNSW search is roughly logarithmic.
  `protected static void`
  `scoreEntryPoints(KnnCollector results, RandomVectorScorer scorer, BitSet visited, int[] eps, Bits acceptOrds, NeighborQueue candidates, float[] scores)`
  `void`
  `search(KnnCollector results, RandomVectorScorer scorer, HnswGraph graph, Bits acceptOrds)`
  Search the graph for the given scorer.
  `static KnnCollector`
  `search(RandomVectorScorer scorer, int topK, OnHeapHnswGraph graph, Bits acceptOrds, int visitedLimit)`
  Search `OnHeapHnswGraph`, this method is thread safe.
  `static void`
  `search(RandomVectorScorer scorer, KnnCollector knnCollector, HnswGraph graph, Bits acceptOrds)`
  See `search(RandomVectorScorer, KnnCollector, HnswGraph, Bits, int)`
  `static void`
  `search(RandomVectorScorer scorer, KnnCollector knnCollector, HnswGraph graph, Bits acceptOrds, int filteredDocCount)`
  Searches the HNSW graph for the nearest neighbors of a query vector.
  `HnswGraphBuilder.GraphBuilderKnnCollector`
  `searchLevel(RandomVectorScorer scorer, int topK, int level, int[] eps, HnswGraph graph)`
  Searches for the nearest neighbors of a query vector in a given level.

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

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

- ## Field Details

  - ### candidates

    protected final NeighborQueue candidates
    Scratch data structures that are used in each `searchLevel(org.apache.lucene.util.hnsw.RandomVectorScorer, int, int, int[], org.apache.lucene.util.hnsw.HnswGraph)` call. These can be expensive to allocate, so they're cleared and reused across calls.

  - ### visited

    protected BitSet visited

  - ### bulkNodes

    protected int[] bulkNodes

  - ### bulkScores

    protected float[] bulkScores

- ## Constructor Details

  - ### HnswGraphSearcher

    public HnswGraphSearcher(NeighborQueue candidates, BitSet visited)
    Creates a new graph searcher.
    Parameters:
      `candidates` - max heap that will track the candidate nodes to explore
      `visited` - bit set that will track nodes that have already been visited

- ## Method Details

  - ### expectedVisitedNodes

    public static int expectedVisitedNodes(int k, int graphSize)
    HNSW search is roughly logarithmic. This doesn't take maxConn into account, but it is a pretty good approximation.
    Parameters:
      `k` - neighbors to find
      `graphSize` - size of the graph
    Returns:
      expected number of visited nodes

  - ### search

    public static void search(RandomVectorScorer scorer, KnnCollector knnCollector, HnswGraph graph, Bits acceptOrds) throws IOException
    See `search(RandomVectorScorer, KnnCollector, HnswGraph, Bits, int)`
    Parameters:
      `scorer` - the scorer to compare the query with the nodes
      `knnCollector` - a hnsw knn collector of top knn results to be returned
      `graph` - the graph values. May represent the entire graph, or a level in a hierarchical graph.
      `acceptOrds` - `Bits` that represents the allowed document ordinals to match, or `null` if they are all allowed to match.
    Throws:
      `IOException`

  - ### search

    public static void search(RandomVectorScorer scorer, KnnCollector knnCollector, HnswGraph graph, Bits acceptOrds, int filteredDocCount) throws IOException
    Searches the HNSW graph for the nearest neighbors of a query vector. If entry points are directly provided via the knnCollector, then the search will be initialized at those points. Otherwise, the search will discover the best entry point per the normal HNSW search algorithm.
    Parameters:
      `scorer` - the scorer to compare the query with the nodes
      `knnCollector` - a hnsw knn collector of top knn results to be returned
      `graph` - the graph values. May represent the entire graph, or a level in a hierarchical graph.
      `acceptOrds` - `Bits` that represents the allowed document ordinals to match, or `null` if they are all allowed to match.
      `filteredDocCount` - the number of docs that pass the filter
    Throws:
      `IOException`

  - ### search

    public static KnnCollector search(RandomVectorScorer scorer, int topK, OnHeapHnswGraph graph, Bits acceptOrds, int visitedLimit) throws IOException
    Search `OnHeapHnswGraph`, this method is thread safe.
    Parameters:
      `scorer` - the scorer to compare the query with the nodes
      `topK` - the number of nodes to be returned
      `graph` - the graph values. May represent the entire graph, or a level in a hierarchical graph.
      `acceptOrds` - `Bits` that represents the allowed document ordinals to match, or `null` if they are all allowed to match.
      `visitedLimit` - the maximum number of nodes that the search is allowed to visit
    Returns:
      a set of collected vectors holding the nearest neighbors found
    Throws:
      `IOException`

  - ### searchLevel

    public HnswGraphBuilder.GraphBuilderKnnCollector searchLevel(RandomVectorScorer scorer, int topK, int level, int[] eps, HnswGraph graph) throws IOException
    Searches for the nearest neighbors of a query vector in a given level.

    If the search stops early because it reaches the visited nodes limit, then the results will be marked incomplete through `NeighborQueue.incomplete()`.

    Parameters:
      `scorer` - the scorer to compare the query with the nodes
      `topK` - the number of nearest to query results to return
      `level` - level to search
      `eps` - the entry points for search at this level expressed as level 0th ordinals
      `graph` - the graph values
    Returns:
      a set of collected vectors holding the nearest neighbors found
    Throws:
      `IOException`

  - ### search

    public void search(KnnCollector results, RandomVectorScorer scorer, HnswGraph graph, Bits acceptOrds) throws IOException
    Search the graph for the given scorer. Gathering results in the provided collector that pass the provided acceptOrds.
    Parameters:
      `results` - the collector to collect the results
      `scorer` - the scorer to compare the query with the nodes
      `graph` - the HNSWGraph
      `acceptOrds` - the ordinals to accept for the results
    Throws:
      `IOException` - When accessing the vectors or graph fails

  - ### scoreEntryPoints

    protected static void scoreEntryPoints(KnnCollector results, RandomVectorScorer scorer, BitSet visited, int[] eps, Bits acceptOrds, NeighborQueue candidates, float[] scores) throws IOException
    Throws:
      `IOException`