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

Package org.apache.lucene.search

# Class ByteVectorSimilarityQuery

java.lang.Object
org.apache.lucene.search.Query
org.apache.lucene.search.ByteVectorSimilarityQuery

public class ByteVectorSimilarityQuery extends Query
Search for all (approximate) byte vectors above a similarity threshold.

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final float`
  `decay`
  `protected final String`
  `field`
  `protected final Query`
  `filter`
  `protected final float`
  `resultSimilarity`
  `protected final KnnSearchStrategy`
  `searchStrategy`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity)`
  Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`.
  `ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity, float decay, Query filter)`
  Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`, with the default `KnnSearchStrategy`.
  `ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity, float decay, Query filter, KnnSearchStrategy searchStrategy)`
  Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`, with a caller-supplied `KnnSearchStrategy`.
  `ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity, Query filter)`
  Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected TopDocs`
  `approximateSearch(LeafReaderContext context, AcceptDocs acceptDocs, int visitLimit, KnnCollectorManager knnCollectorManager)`
  `Weight`
  `createWeight(IndexSearcher searcher, ScoreMode scoreMode, float boost)`
  Expert: Constructs an appropriate Weight implementation for this query.
  `boolean`
  `equals(Object o)`
  Override and implement query instance equivalence properly in a subclass.
  `protected KnnCollectorManager`
  `getKnnCollectorManager()`
  Returns a `KnnCollectorManager` that always builds a `VectorSimilarityCollector` configured with this query's `searchStrategy`.
  `KnnSearchStrategy`
  `getSearchStrategy()`
  `int`
  `hashCode()`
  Override and implement query hash code properly in a subclass.
  `String`
  `toString(String field)`
  Prints a query to a string, with `field` assumed to be the default field and omitted.
  `void`
  `visit(QueryVisitor visitor)`
  Recurse through the query tree, visiting any child queries.

  ### Methods inherited from class org.apache.lucene.search.Query

  `classHash, rewrite, sameClassAs, toString`

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

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

- ## Field Details

  - ### field

    protected final String field

  - ### resultSimilarity

    protected final float resultSimilarity

  - ### decay

    protected final float decay

  - ### filter

    protected final Query filter

  - ### searchStrategy

    protected final KnnSearchStrategy searchStrategy

- ## Constructor Details

  - ### ByteVectorSimilarityQuery

    public ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity, float decay, Query filter, KnnSearchStrategy searchStrategy)
    Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`, with a caller-supplied `KnnSearchStrategy`. If a filter is applied, it traverses as many nodes as the cost of the filter, and then falls back to exact search if results are incomplete.
    Parameters:
      `field` - a field that has been indexed as a `KnnByteVectorField`.
      `target` - the target of the search.
      `resultSimilarity` - similarity score for result collection.
      `decay` - decay factor for graph traversal buffer.
      `filter` - a filter applied before the vector search.
      `searchStrategy` - the `KnnSearchStrategy` to use during graph search. If `null`, this query's own default is used: an `KnnSearchStrategy.Hnsw` with `filteredSearchThreshold == 0`, which preserves this query's filter handling. Note this differs from `KnnSearchStrategy.Hnsw.DEFAULT`, which uses a threshold of 60. The underlying format may not support all strategies and is free to ignore the requested strategy.

  - ### ByteVectorSimilarityQuery

    public ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity, float decay, Query filter)
    Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`, with the default `KnnSearchStrategy`. If a filter is applied, it traverses as many nodes as the cost of the filter, and then falls back to exact search if results are incomplete.
    Parameters:
      `field` - a field that has been indexed as a `KnnByteVectorField`.
      `target` - the target of the search.
      `resultSimilarity` - similarity score for result collection.
      `decay` - decay factor for graph traversal buffer.
      `filter` - a filter applied before the vector search.

  - ### ByteVectorSimilarityQuery

    public ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity, Query filter)
    Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`. If a filter is applied, it traverses as many nodes as the cost of the filter, and then falls back to exact search if results are incomplete.
    Parameters:
      `field` - a field that has been indexed as a `KnnByteVectorField`.
      `target` - the target of the search.
      `resultSimilarity` - similarity score for result collection.
      `filter` - a filter applied before the vector search.

  - ### ByteVectorSimilarityQuery

    public ByteVectorSimilarityQuery(String field, byte[] target, float resultSimilarity)
    Search for all (approximate) byte vectors above a similarity threshold using `VectorSimilarityCollector`.
    Parameters:
      `field` - a field that has been indexed as a `KnnByteVectorField`.
      `target` - the target of the search.
      `resultSimilarity` - similarity score for result collection.

- ## Method Details

  - ### approximateSearch

    protected TopDocs approximateSearch(LeafReaderContext context, AcceptDocs acceptDocs, int visitLimit, KnnCollectorManager knnCollectorManager) throws IOException
    Throws:
      `IOException`

  - ### toString

    public String toString(String field)
    Description copied from class: `Query`
    Prints a query to a string, with `field` assumed to be the default field and omitted.
    Specified by:
      `toString` in class `Query`

  - ### equals

    public boolean equals(Object o)
    Description copied from class: `Query`
    Override and implement query instance equivalence properly in a subclass. This is required so that `QueryCache` works properly.

    Typically a query will be equal to another only if it's an instance of the same class and its document-filtering properties are identical to those of the other instance. Utility methods are provided for certain repetitive code.

    See Also:
      - `Query.sameClassAs(Object)`
      - `Query.classHash()`

  - ### hashCode

    public int hashCode()
    Description copied from class: `Query`
    Override and implement query hash code properly in a subclass. This is required so that `QueryCache` works properly.
    See Also:
      - `Query.equals(Object)`

  - ### getKnnCollectorManager

    protected KnnCollectorManager getKnnCollectorManager()
    Returns a `KnnCollectorManager` that always builds a `VectorSimilarityCollector` configured with this query's `searchStrategy`.

    The manager's `strategy` and `LeafReaderContext` parameters are intentionally ignored: top-k queries may override the strategy on a per-search basis, but similarity- threshold queries pin the strategy to the query's own value at construction time so that `Query.equals(java.lang.Object)` / `getSearchStrategy()` remain a faithful description of search behavior.

  - ### getSearchStrategy

    public KnnSearchStrategy getSearchStrategy()
    Returns:
      the `KnnSearchStrategy` used during graph search.

  - ### createWeight

    public Weight createWeight(IndexSearcher searcher, ScoreMode scoreMode, float boost) throws IOException
    Description copied from class: `Query`
    Expert: Constructs an appropriate Weight implementation for this query.

    Only implemented by primitive queries, which re-write to themselves.

    Overrides:
      `createWeight` in class `Query`
    Parameters:
      `scoreMode` - How the produced scorers will be consumed.
      `boost` - The boost that is propagated by the parent queries.
    Throws:
      `IOException`

  - ### visit

    public void visit(QueryVisitor visitor)
    Description copied from class: `Query`
    Recurse through the query tree, visiting any child queries.
    Specified by:
      `visit` in class `Query`
    Parameters:
      `visitor` - a QueryVisitor to be called by each query in the tree