Package org.apache.lucene.search

Class KnnVectorQuery

java.lang.Object

org.apache.lucene.search.Query

org.apache.lucene.search.KnnVectorQuery

public class KnnVectorQuery
extends Query

Uses KnnVectorsReader.search(java.lang.String, float[], int, org.apache.lucene.util.Bits, int) to perform nearest neighbour search.

This query also allows for performing a kNN search subject to a filter. In this case, it first executes the filter for each leaf, then chooses a strategy dynamically:

• If the filter cost is less than k, just execute an exact search
• Otherwise run a kNN search subject to the filter
• If the kNN search visits too many vectors without completing, stop and run an exact search

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	KnnVectorQuery.DocAndScoreQuery	Caches the results of a KnnVector search: a list of docs and their scores

Field Summary

Fields

Modifier and Type	Field	Description
private final String	field
private final Query	filter
private final int	k
private static final TopDocs	NO_RESULTS
private final float[]	target

Constructor Summary

Constructors

Constructor	Description
KnnVectorQuery(String field, float[] target, int k)	Find the k nearest documents to the target vector according to the vectors in the given field.
KnnVectorQuery(String field, float[] target, int k, Query filter)	Find the k nearest documents to the target vector according to the vectors in the given field.

Method Summary

Modifier and Type	Method	Description
private TopDocs	approximateSearch(LeafReaderContext context, Bits acceptDocs, int visitedLimit)
private BitSet	createBitSet(DocIdSetIterator iterator, Bits liveDocs, int maxDoc)
private Query	createRewrittenQuery(IndexReader reader, TopDocs topK)
boolean	equals(Object obj)	Override and implement query instance equivalence properly in a subclass.
protected TopDocs	exactSearch(LeafReaderContext context, DocIdSetIterator acceptIterator)
private int[]	findSegmentStarts(IndexReader reader, int[] docs)
int	hashCode()	Override and implement query hash code properly in a subclass.
Query	rewrite(IndexReader reader)	Expert: called to re-write queries into primitive queries.
private TopDocs	searchLeaf(LeafReaderContext ctx, Weight filterWeight)
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

Field Details

NO_RESULTS

private static final TopDocs NO_RESULTS

field

private final String field

target

private final float[] target

k

private final int k

filter

private final Query filter

Constructor Details

KnnVectorQuery

public KnnVectorQuery(String field,
 float[] target,
 int k)

Find the k nearest documents to the target vector according to the vectors in the given field. target vector.

Parameters:

field - a field that has been indexed as a KnnVectorField.

target - the target of the search

k - the number of documents to find

Throws:

IllegalArgumentException - if k is less than 1

KnnVectorQuery

public KnnVectorQuery(String field,
 float[] target,
 int k,
 Query filter)

Find the k nearest documents to the target vector according to the vectors in the given field. target vector.

Parameters:

field - a field that has been indexed as a KnnVectorField.

target - the target of the search

k - the number of documents to find

filter - a filter applied before the vector search

Throws:

IllegalArgumentException - if k is less than 1

Method Details

rewrite

public Query rewrite(IndexReader reader)
              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.

Overrides:

rewrite in class Query

Throws:

IOException

See Also:

• IndexSearcher.rewrite(Query)

searchLeaf

private TopDocs searchLeaf(LeafReaderContext ctx,
 Weight filterWeight)
                    throws IOException

Throws:

IOException

createBitSet

private BitSet createBitSet(DocIdSetIterator iterator,
 Bits liveDocs,
 int maxDoc)
                     throws IOException

Throws:

IOException

approximateSearch

private TopDocs approximateSearch(LeafReaderContext context,
 Bits acceptDocs,
 int visitedLimit)
                           throws IOException

Throws:

IOException

exactSearch

protected TopDocs exactSearch(LeafReaderContext context,
 DocIdSetIterator acceptIterator)
                       throws IOException

Throws:

IOException

createRewrittenQuery

private Query createRewrittenQuery(IndexReader reader,
 TopDocs topK)

findSegmentStarts

private int[] findSegmentStarts(IndexReader reader,
 int[] docs)

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

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

equals

public boolean equals(Object obj)

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 that other instance. Utility methods are provided for certain repetitive code.

Specified by:

equals in class Query

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.

Specified by:

hashCode in class Query

See Also:

• Query.equals(Object)