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

Package org.apache.lucene.util.hnsw

# Class FilteredHnswGraphSearcher

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

public class FilteredHnswGraphSearcher extends HnswGraphSearcher
Searches an HNSW graph to find nearest neighbors to a query vector. This particular implementation is optimized for a filtered search, inspired by the ACORN-1 algorithm. However, this implementation is augmented in some ways, mainly:

- It dynamically determines when the optimized filter step should occur based on some filtered lambda. This is done per small world
- The graph searcher doesn't always explore all the extended neighborhood and the number of additional candidates is predicated on the original candidate's filtered percentage.

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.util.hnsw.HnswGraphSearcher

  `bulkNodes, bulkScores, candidates, visited`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static FilteredHnswGraphSearcher`
  `create(int k, HnswGraph graph, int filterSize, Bits acceptOrds)`
  Creates a new filtered graph searcher.
  `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.

  ### Methods inherited from class org.apache.lucene.util.hnsw.HnswGraphSearcher

  `expectedVisitedNodes, search, search, search, searchLevel`

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

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

- ## Method Details

  - ### create

    public static FilteredHnswGraphSearcher create(int k, HnswGraph graph, int filterSize, Bits acceptOrds)
    Creates a new filtered graph searcher.
    Parameters:
      `k` - the number of nearest neighbors to find
      `graph` - the graph to search
      `filterSize` - the number of vectors that pass the accepted ords filter
      `acceptOrds` - the accepted ords filter
    Returns:
      a new graph searcher optimized for filtered search

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