Module org.elasticsearch.server

Package org.elasticsearch.search.vectors

Class KnnVectorQueryBuilder

java.lang.Object

org.elasticsearch.index.query.AbstractQueryBuilder<KnnVectorQueryBuilder>

org.elasticsearch.index.query.LeafQueryBuilder<KnnVectorQueryBuilder>

org.elasticsearch.search.vectors.KnnVectorQueryBuilder

All Implemented Interfaces:

NamedWriteable, VersionedNamedWriteable, Writeable, QueryBuilder, Rewriteable<QueryBuilder>, ToXContent, ToXContentObject

public class KnnVectorQueryBuilder
extends LeafQueryBuilder<KnnVectorQueryBuilder>

A query that performs kNN search using Lucene's KnnFloatVectorQuery or KnnByteVectorQuery.

Nested Class Summary

Nested classes/interfaces inherited from interface org.elasticsearch.xcontent.ToXContent

ToXContent.DelegatingMapParams, ToXContent.MapParams, ToXContent.Params

Nested classes/interfaces inherited from interface org.elasticsearch.common.io.stream.Writeable

Writeable.Reader<V>, Writeable.Writer<V>

Field Summary

Fields

Modifier and Type	Field	Description
static final TransportVersion	AUTO_PREFILTERING
static final ParseField	FIELD_FIELD
static final ParseField	FILTER_FIELD
static final ParseField	K_FIELD
static final String	NAME
static final ParseField	NUM_CANDS_FIELD
static final ConstructingObjectParser<KnnVectorQueryBuilder,Void>	PARSER
static final ParseField	QUERY_VECTOR_BUILDER_FIELD
static final ParseField	QUERY_VECTOR_FIELD
static final ParseField	RESCORE_VECTOR_FIELD
static final Set<Class<? extends QueryBuilder>>	UNSUPPORTED_AUTO_PREFILTERING_QUERY_TYPES	Semantic knn queries will be wrapped in a nested query as the target field is the nested embeddings vector.
static final ParseField	VECTOR_SIMILARITY_FIELD
static final TransportVersion	VISIT_PERCENTAGE
static final ParseField	VISIT_PERCENTAGE_FIELD

Fields inherited from class org.elasticsearch.index.query.AbstractQueryBuilder

boost, BOOST_FIELD, DEFAULT_BOOST, NAME_FIELD, queryName

Fields inherited from interface org.elasticsearch.index.query.Rewriteable

MAX_REWRITE_ROUNDS

Fields inherited from interface org.elasticsearch.xcontent.ToXContent

EMPTY, EMPTY_PARAMS

Constructor Summary

Constructors

Constructor	Description
KnnVectorQueryBuilder(String fieldName, byte[] queryVector, Integer k, Integer numCands, Float visitPercentage, RescoreVectorBuilder rescoreVectorBuilder, Float vectorSimilarity)
KnnVectorQueryBuilder(String fieldName, float[] queryVector, Integer k, Integer numCands, Float visitPercentage, RescoreVectorBuilder rescoreVectorBuilder, Float vectorSimilarity)
KnnVectorQueryBuilder(String fieldName, QueryVectorBuilder queryVectorBuilder, Integer k, Integer numCands, Float visitPercentage, Float vectorSimilarity)
KnnVectorQueryBuilder(String fieldName, VectorData queryVector, Integer k, Integer numCands, Float visitPercentage, RescoreVectorBuilder rescoreVectorBuilder, Float vectorSimilarity)
KnnVectorQueryBuilder(StreamInput in)

Method Summary

Modifier and Type	Method	Description
KnnVectorQueryBuilder	addFilterQueries(List<QueryBuilder> filterQueries)
KnnVectorQueryBuilder	addFilterQuery(QueryBuilder filterQuery)
protected boolean	doEquals(KnnVectorQueryBuilder other)	Indicates whether some other QueryBuilder object of the same type is "equal to" this one.
protected int	doHashCode()
protected QueryBuilder	doRewrite(QueryRewriteContext ctx)
protected org.apache.lucene.search.Query	doToQuery(SearchExecutionContext context)
protected void	doWriteTo(StreamOutput out)
protected void	doXContent(XContentBuilder builder, ToXContent.Params params)
List<QueryBuilder>	filterQueries()
static KnnVectorQueryBuilder	fromXContent(XContentParser parser)
String	getFieldName()
TransportVersion	getMinimalSupportedVersion()	The minimal version of the recipient this object can be sent to.
Float	getVectorSimilarity()
String	getWriteableName()	Returns the name of the writeable object
boolean	isAutoPrefilteringEnabled()
Integer	k()
Integer	numCands()
VectorData	queryVector()
QueryVectorBuilder	queryVectorBuilder()
RescoreVectorBuilder	rescoreVectorBuilder()
KnnVectorQueryBuilder	setAutoPrefilteringEnabled(boolean isAutoPrefilteringEnabled)
KnnVectorQueryBuilder	setFilterQueries(List<QueryBuilder> filterQueries)
Float	visitPercentage()

Methods inherited from class org.elasticsearch.index.query.LeafQueryBuilder

doToQuery

Methods inherited from class org.elasticsearch.index.query.AbstractQueryBuilder

addValidationError, boost, boost, boostAndQueryNameToXContent, checkNegativeBoost, declareStandardFields, doCoordinatorRewrite, doIndexMetadataRewrite, doInnerHitsRewrite, doSearchRewrite, equals, extractInnerHitBuilders, getMaxNestedDepth, getName, hashCode, parseInnerQueryBuilder, parseTopLevelQuery, parseTopLevelQuery, printBoostAndQueryName, queryName, queryName, readQueries, requireValue, rewrite, setMaxNestedDepth, throwParsingExceptionOnMultipleFields, toQuery, toQuery, toString, toXContent, writeQueries, writeTo

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.elasticsearch.xcontent.ToXContentObject

isFragment

Methods inherited from interface org.elasticsearch.common.io.stream.VersionedNamedWriteable

supportsVersion

Field Details

AUTO_PREFILTERING

public static final TransportVersion AUTO_PREFILTERING

NAME

public static final String NAME

See Also:

• Constant Field Values

FIELD_FIELD

public static final ParseField FIELD_FIELD

K_FIELD

public static final ParseField K_FIELD

NUM_CANDS_FIELD

public static final ParseField NUM_CANDS_FIELD

VISIT_PERCENTAGE_FIELD

public static final ParseField VISIT_PERCENTAGE_FIELD

QUERY_VECTOR_FIELD

public static final ParseField QUERY_VECTOR_FIELD

VECTOR_SIMILARITY_FIELD

public static final ParseField VECTOR_SIMILARITY_FIELD

FILTER_FIELD

public static final ParseField FILTER_FIELD

QUERY_VECTOR_BUILDER_FIELD

public static final ParseField QUERY_VECTOR_BUILDER_FIELD

RESCORE_VECTOR_FIELD

public static final ParseField RESCORE_VECTOR_FIELD

PARSER

public static final ConstructingObjectParser<KnnVectorQueryBuilder,Void> PARSER

UNSUPPORTED_AUTO_PREFILTERING_QUERY_TYPES

public static final Set<Class<? extends QueryBuilder>> UNSUPPORTED_AUTO_PREFILTERING_QUERY_TYPES

Semantic knn queries will be wrapped in a nested query as the target field is the nested embeddings vector. knn pre-filtering does not handle nested filters when the knn itself is in a nested query. (see elasticsearch/#138410)

VISIT_PERCENTAGE

public static final TransportVersion VISIT_PERCENTAGE

Constructor Details

KnnVectorQueryBuilder

public KnnVectorQueryBuilder(String fieldName,
 float[] queryVector,
 Integer k,
 Integer numCands,
 Float visitPercentage,
 RescoreVectorBuilder rescoreVectorBuilder,
 Float vectorSimilarity)

KnnVectorQueryBuilder

public KnnVectorQueryBuilder(String fieldName,
 QueryVectorBuilder queryVectorBuilder,
 Integer k,
 Integer numCands,
 Float visitPercentage,
 Float vectorSimilarity)

KnnVectorQueryBuilder

public KnnVectorQueryBuilder(String fieldName,
 byte[] queryVector,
 Integer k,
 Integer numCands,
 Float visitPercentage,
 RescoreVectorBuilder rescoreVectorBuilder,
 Float vectorSimilarity)

KnnVectorQueryBuilder

public KnnVectorQueryBuilder(String fieldName,
 VectorData queryVector,
 Integer k,
 Integer numCands,
 Float visitPercentage,
 RescoreVectorBuilder rescoreVectorBuilder,
 Float vectorSimilarity)

KnnVectorQueryBuilder

public KnnVectorQueryBuilder(StreamInput in)
                      throws IOException

Throws:

IOException

Method Details

fromXContent

public static KnnVectorQueryBuilder fromXContent(XContentParser parser)

getFieldName

public String getFieldName()

queryVector

@Nullable
public VectorData queryVector()

getVectorSimilarity

@Nullable
public Float getVectorSimilarity()

k

public Integer k()

numCands

public Integer numCands()

visitPercentage

public Float visitPercentage()

filterQueries

public List<QueryBuilder> filterQueries()

queryVectorBuilder

@Nullable
public QueryVectorBuilder queryVectorBuilder()

rescoreVectorBuilder

public RescoreVectorBuilder rescoreVectorBuilder()

addFilterQuery

public KnnVectorQueryBuilder addFilterQuery(QueryBuilder filterQuery)

addFilterQueries

public KnnVectorQueryBuilder addFilterQueries(List<QueryBuilder> filterQueries)

setFilterQueries

public KnnVectorQueryBuilder setFilterQueries(List<QueryBuilder> filterQueries)

isAutoPrefilteringEnabled

public boolean isAutoPrefilteringEnabled()

doWriteTo

protected void doWriteTo(StreamOutput out)
                  throws IOException

Specified by:

doWriteTo in class AbstractQueryBuilder<KnnVectorQueryBuilder>

Throws:

IOException

doXContent

protected void doXContent(XContentBuilder builder,
 ToXContent.Params params)
                   throws IOException

Specified by:

doXContent in class AbstractQueryBuilder<KnnVectorQueryBuilder>

Throws:

IOException

getWriteableName

public String getWriteableName()

Description copied from interface: VersionedNamedWriteable

Returns the name of the writeable object

doRewrite

protected QueryBuilder doRewrite(QueryRewriteContext ctx)
                          throws IOException

Overrides:

doRewrite in class AbstractQueryBuilder<KnnVectorQueryBuilder>

Throws:

IOException

doToQuery

protected org.apache.lucene.search.Query doToQuery(SearchExecutionContext context)
                                            throws IOException

Specified by:

doToQuery in class LeafQueryBuilder<KnnVectorQueryBuilder>

Throws:

IOException

doHashCode

protected int doHashCode()

Specified by:

doHashCode in class AbstractQueryBuilder<KnnVectorQueryBuilder>

doEquals

protected boolean doEquals(KnnVectorQueryBuilder other)

Description copied from class: AbstractQueryBuilder

Indicates whether some other QueryBuilder object of the same type is "equal to" this one.

Specified by:

doEquals in class AbstractQueryBuilder<KnnVectorQueryBuilder>

getMinimalSupportedVersion

public TransportVersion getMinimalSupportedVersion()

Description copied from interface: VersionedNamedWriteable

The minimal version of the recipient this object can be sent to. See VersionedNamedWriteable.supportsVersion(TransportVersion) for the default serialization check.

setAutoPrefilteringEnabled

public KnnVectorQueryBuilder setAutoPrefilteringEnabled(boolean isAutoPrefilteringEnabled)