Module spring.data.mongodb

Package org.springframework.data.mongodb.core.aggregation

Class VectorSearchOperation

java.lang.Object

org.springframework.data.mongodb.core.aggregation.VectorSearchOperation

All Implemented Interfaces:

AggregationOperation

public class VectorSearchOperation
extends Object
implements AggregationOperation

Performs a semantic search on data in your Atlas cluster. This stage is only available for Atlas Vector Search. Vector data must be less than or equal to 4096 dimensions in width.

Limitations

You cannot use this stage together with:

• Lookup stages
• Facet stage

Since:

4.5

Author:

Christoph Strobl, Mark Paluch

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	VectorSearchOperation.LimitContributor	Fluent API to configure a limit on the VectorSearchOperation builder.
static interface	VectorSearchOperation.PathContributor	Fluent API to configure a path on the VectorSearchOperation builder.
static interface	VectorSearchOperation.QueryPath<T>	Interface describing a query path contract.
static class	VectorSearchOperation.QueryPaths	Value object capturing query paths.
static enum	VectorSearchOperation.SearchType	Search type, ANN as approximation or ENN for exact search.
static class	VectorSearchOperation.SimplePath
static interface	VectorSearchOperation.VectorContributor	Fluent API to configure a vector on the VectorSearchOperation builder.

Method Summary

Modifier and Type	Method	Description
VectorSearchOperation	filter(org.bson.Document filter)	Criteria expression that compares an indexed field with a boolean, date, objectId, number (not decimals), string, or UUID to use as a pre-filter.
VectorSearchOperation	filter(CriteriaDefinition filter)	Criteria expression that compares an indexed field with a boolean, date, objectId, number (not decimals), string, or UUID to use as a pre-filter.
String	getOperator()	Return the MongoDB operator that is used for this AggregationOperation.
VectorSearchOperation	numCandidates(int numCandidates)	Number of nearest neighbors to use during the search.
static VectorSearchOperation.PathContributor	search(String index)	Entrypoint to build a VectorSearchOperation starting from the index name to search.
VectorSearchOperation	searchType(VectorSearchOperation.SearchType searchType)	Configure the search type to use.
org.bson.Document	toDocument(AggregationOperationContext context)	Turns the AggregationOperation into a Document by using the given AggregationOperationContext.
List<org.bson.Document>	toPipelineStages(AggregationOperationContext context)	Turns the AggregationOperation into list of stages by using the given AggregationOperationContext.
VectorSearchOperation	withFilterBySore(Consumer<Criteria> score)	Add a MatchOperation stage targeting the score field name.
VectorSearchOperation	withSearchScore()	Add a AddFieldsOperation stage including the search score using score as field name.
VectorSearchOperation	withSearchScore(String scoreFieldName)	Add a AddFieldsOperation stage including the search score using scoreFieldName as field name.

Methods inherited from class java.lang.Object

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

Method Details

search

public static VectorSearchOperation.PathContributor search(String index)

Entrypoint to build a VectorSearchOperation starting from the index name to search. Atlas Vector Search doesn't return results if you misspell the index name or if the specified index doesn't already exist on the cluster.

Parameters:

index - must not be null or empty.

Returns:

new instance of VectorSearchOperation.PathContributor.

searchType

@Contract("_ -> new")
public VectorSearchOperation searchType(VectorSearchOperation.SearchType searchType)

Configure the search type to use. VectorSearchOperation.SearchType.ENN leads to an exact search while VectorSearchOperation.SearchType.ANN uses exact=false.

Parameters:

searchType - must not be null.

Returns:

a new VectorSearchOperation with VectorSearchOperation.SearchType applied.

filter

@Contract("_ -> new")
public VectorSearchOperation filter(CriteriaDefinition filter)

Criteria expression that compares an indexed field with a boolean, date, objectId, number (not decimals), string, or UUID to use as a pre-filter.

Atlas Vector Search supports only the filters for the following MQL match expressions:

• $gt
• $lt
• $gte
• $lte
• $eq
• $ne
• $in
• $nin
• $nor
• $not
• $and
• $or

Parameters:

filter - must not be null.

Returns:

a new VectorSearchOperation with CriteriaDefinition applied.

filter

@Contract("_ -> new")
public VectorSearchOperation filter(org.bson.Document filter)

Criteria expression that compares an indexed field with a boolean, date, objectId, number (not decimals), string, or UUID to use as a pre-filter.

Atlas Vector Search supports only the filters for the following MQL match expressions:

• $gt
• $lt
• $gte
• $lte
• $eq
• $ne
• $in
• $nin
• $nor
• $not
• $and
• $or

Parameters:

filter - must not be null.

Returns:

a new VectorSearchOperation with CriteriaDefinition applied.

numCandidates

@Contract("_ -> new")
public VectorSearchOperation numCandidates(int numCandidates)

Number of nearest neighbors to use during the search. Value must be less than or equal to (<=) 10000. You can't specify a number less than the number of documents to return (limit). This field is required if searchType(SearchType) is VectorSearchOperation.SearchType.ANN or VectorSearchOperation.SearchType.DEFAULT.

Parameters:

numCandidates - number of nearest neighbors to use during the search

Returns:

a new VectorSearchOperation with numCandidates applied.

withSearchScore

@Contract("-> new")
public VectorSearchOperation withSearchScore()

Add a AddFieldsOperation stage including the search score using score as field name.

Returns:

a new VectorSearchOperation with search score applied.

See Also:

• withSearchScore(String)

withSearchScore

@Contract("_ -> new")
public VectorSearchOperation withSearchScore(String scoreFieldName)

Add a AddFieldsOperation stage including the search score using scoreFieldName as field name.

Parameters:

scoreFieldName - name of the score field.

Returns:

a new VectorSearchOperation with scoreFieldName applied.

See Also:

• withSearchScore()

withFilterBySore

@Contract("_ -> new")
public VectorSearchOperation withFilterBySore(Consumer<Criteria> score)

Add a MatchOperation stage targeting the score field name. Implies that the score field is present by either reusing a previous AddFieldsOperation from withSearchScore() or withSearchScore(String) or by adding a new AddFieldsOperation stage.

Returns:

a new VectorSearchOperation with search score filter applied.

toDocument

public org.bson.Document toDocument(AggregationOperationContext context)

Description copied from interface: AggregationOperation

Turns the AggregationOperation into a Document by using the given AggregationOperationContext.

Specified by:

toDocument in interface AggregationOperation

Parameters:

context - the AggregationOperationContext to operate within. Must not be null.

Returns:

the Document

toPipelineStages

public List<org.bson.Document> toPipelineStages(AggregationOperationContext context)

Description copied from interface: AggregationOperation

Turns the AggregationOperation into list of stages by using the given AggregationOperationContext. This allows a single AggregationOptions to add additional stages for eg. $sort or $limit.

Specified by:

toPipelineStages in interface AggregationOperation

Parameters:

context - the AggregationOperationContext to operate within. Must not be null.

Returns:

the pipeline stages to run through. Never null.

getOperator

public String getOperator()

Description copied from interface: AggregationOperation

Return the MongoDB operator that is used for this AggregationOperation. Aggregation operations should implement this method to avoid document rendering.

Specified by:

getOperator in interface AggregationOperation

Returns:

the operator used for this AggregationOperation.