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

Package org.apache.lucene.search

# Class RescoreTopNQuery

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

public class RescoreTopNQuery extends Query
A Query that re-scores another Query with a `DoubleValuesSource` function and cut-off the results at top N. Unlike `Rescorer` which does rescoring at post-collection phase, this Query does the rescoring at rewrite() phase. The reason it operates in rewrite phase is to be compatible with KNN vector query, where the results are collected upfront, but it can work with any type of Query. Unlike or `FunctionScoreQuery`, this Query will work even with the no-scoring `ScoreMode`.

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RescoreTopNQuery(Query query, DoubleValuesSource valuesSource, int n)`
  Execute the inner Query, re-score using a customizable DoubleValueSource and trim down the result to k

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Query`
  `createFullPrecisionRescorerQuery(Query in, float[] targetVector, String field, int n)`
  Utility method to create a new RescoreTopNQuery which uses full-precision vectors for rescoring.
  `static Query`
  `createLateInteractionQuery(Query in, int n, String fieldName, float[][] queryVector, VectorSimilarityFunction vectorSimilarityFunction)`
  Creates a `RescoreTopNQuery` that computes top N results using multi-vector similarity comparisons against a late interaction field.
  `boolean`
  `equals(Object o)`
  Override and implement query instance equivalence properly in a subclass.
  `int`
  `hashCode()`
  Override and implement query hash code properly in a subclass.
  `Query`
  `rewrite(IndexSearcher indexSearcher)`
  Expert: called to re-write queries into primitive queries.
  `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, createWeight, sameClassAs, toString`

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

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

- ## Constructor Details

  - ### RescoreTopNQuery

    public RescoreTopNQuery(Query query, DoubleValuesSource valuesSource, int n)
    Execute the inner Query, re-score using a customizable DoubleValueSource and trim down the result to k
    Parameters:
      `query` - the query to execute as initial phase
      `valuesSource` - the double value source to re-score
      `n` - the number of documents to find
    Throws:
      `IllegalArgumentException` - if `n` is less than 1

- ## Method Details

  - ### rewrite

    public Query rewrite(IndexSearcher indexSearcher) throws IOException
    Description copied from class: `Query`
    Expert: called to re-write queries into primitive queries. For example, a PrefixQuery will be rewritten into a BooleanQuery that consists of TermQuerys.

    Callers are expected to call `rewrite` multiple times if necessary, until the rewritten query is the same as the original query.

    The rewrite process may be able to make use of IndexSearcher's executor and be executed in parallel if the executor is provided.

    Overrides:
      `rewrite` in class `Query`
    Throws:
      `IOException`
    See Also:
      - `IndexSearcher.rewrite(Query)`

  - ### 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.
    Specified by:
      `hashCode` in class `Query`
    See Also:
      - `Query.equals(Object)`

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

    Specified by:
      `equals` in class `Query`
    See Also:
      - `Query.sameClassAs(Object)`
      - `Query.classHash()`

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

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

  - ### createFullPrecisionRescorerQuery

    public static Query createFullPrecisionRescorerQuery(Query in, float[] targetVector, String field, int n)
    Utility method to create a new RescoreTopNQuery which uses full-precision vectors for rescoring.
    Parameters:
      `in` - the inner Query to rescore
      `targetVector` - the target vector to compute score
      `field` - the vector field to compute score
      `n` - the number of results to keep
    Returns:
      the RescoreTopNQuery

  - ### createLateInteractionQuery

    public static Query createLateInteractionQuery(Query in, int n, String fieldName, float[][] queryVector, VectorSimilarityFunction vectorSimilarityFunction)
    Creates a `RescoreTopNQuery` that computes top N results using multi-vector similarity comparisons against a late interaction field.

    Note: This query computes late interaction field similarity for the entire match-set of wrapped query, and returns a new query with only top-N hits in the match-set. This is typically useful in combining a query's results with other queries for hybrid search. To simply rerank the top N hits without scoring entire match-set, see `LateInteractionRescorer`.

    Parameters:
      `in` - the inner Query to rescore
      `n` - number of results to keep
      `fieldName` - the `LateInteractionField` for recomputing top N hits
      `queryVector` - query multi-vector to use for similarity comparisons
      `vectorSimilarityFunction` - function to use for vector similarity comparisons.