Package com.oracle.coherence.ai.search

Class SimilaritySearch<K,V,T>

java.lang.Object

com.oracle.coherence.ai.search.SimilaritySearch<K,V,T>

Type Parameters:

K - the type of the cache key

V - the type of the cache value

T - the type of the vector

All Implemented Interfaces:

ExternalizableLite, PortableObject, InvocableMap.EntryAggregator<K,V,List<QueryResult<K,V>>>, InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>, Serializable

public class SimilaritySearch<K,V,T>
extends Object
implements InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>, ExternalizableLite, PortableObject

An InvocableMap.StreamingAggregator to execute a similarity query.

Since:

24.09

Author:

Jonathan Knight 2024.07.19, Aleks Seovic 2024.07.25

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SimilaritySearch.ResultConverter<K,V>

Field Summary

Fields

Modifier and Type	Field	Description
protected DistanceAlgorithm<T>	m_algorithm	The DistanceAlgorithm to execute.
protected ValueExtractor<? super V,? extends Vector<T>>	m_extractor	The ValueExtractor to extract the vector from the entry value.
protected boolean	m_fBruteForce	A flag indicating whether to ignore any VectorIndex that may be present and just use the algorithm directly (i.e. use a brute force calculation)
protected Filter<?>	m_filter	An optional Filter to use to filter the search results.
protected int	m_nMaxResults	The maximum number of results to return.
protected final SortedBag<BinaryQueryResult>	m_results	The interim results for the aggregator.
protected Vector<T>	m_vector	The Vector to extract the vector from the entry value.

Fields inherited from interface com.tangosol.util.InvocableMap.StreamingAggregator

ALLOW_INCONSISTENCIES, BY_MEMBER, BY_PARTITION, PARALLEL, PRESENT_ONLY, RETAINS_ENTRIES, SERIAL

Constructor Summary

Constructors

Constructor	Description
SimilaritySearch()	Default constructor for serialization.
SimilaritySearch(ValueExtractor<? super V,? extends Vector<T>> extractor, Vector<T> vector, int maxResults)	Create a SimilaritySearch aggregator that will use cosine distance to calculate and return up to maxResults results that are closest to the specified vector.

Method Summary

Modifier and Type	Method	Description
boolean	accumulate(InvocableMap.Entry<? extends K,? extends V> entry)	Accumulate one entry into the result.
boolean	accumulate(Streamer<? extends InvocableMap.Entry<? extends K,? extends V>> streamer)	Accumulate multiple entries into the result.
SimilaritySearch<K,V,T>	algorithm(DistanceAlgorithm<T> algorithm)	Set the algorithm to use for distance calculation between vectors.
SimilaritySearch<K,V,T>	bruteForce()	Force brute force search, ignoring any available indexes.
protected boolean	bruteForce(Streamer<? extends InvocableMap.Entry<? extends K,? extends V>> streamer, InvocableMap.Entry<? extends K,? extends V> entry)
int	characteristics()	A bit mask representing the set of characteristics of this aggregator.
boolean	combine(List<BinaryQueryResult> partialResult)	Merge another partial result into the result.
SimilaritySearch<K,V,T>	filter(Filter<?> filter)	Set the filter to use to limit the set of entries to search.
List<QueryResult<K,V>>	finalizeResult()	Return the final result of the aggregation.
List<QueryResult<K,V>>	finalizeResult(Converter<Binary,?> converterBin)	Return the final result of the aggregation.
DistanceAlgorithm<T>	getAlgorithm()
ValueExtractor<? super V,? extends Vector<T>>	getExtractor()
Filter<?>	getFilter()
int	getMaxResults()
List<BinaryQueryResult>	getPartialResult()	Return the partial result of the aggregation.
Vector<T>	getVector()
boolean	isBruteForce()
void	readExternal(PofReader in)	Restore the contents of a user type instance by reading its state using the specified PofReader object.
void	readExternal(DataInput in)	Restore the contents of this object by loading the object's state from the passed DataInput object.
protected boolean	searchPartition(BinaryEntry binaryEntry, Vector<T> vector)	If a VectorIndex exists for the specified partition, then use it to perform the KNN search.
InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>	supply()	Create a new instance of this aggregator.
void	writeExternal(PofWriter out)	Save the contents of a POF user type instance by writing its state using the specified PofWriter object.
void	writeExternal(DataOutput out)	Save the contents of this object by storing the object's state into the passed DataOutput object.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.tangosol.util.InvocableMap.StreamingAggregator

aggregate, isAllowInconsistencies, isByMember, isByPartition, isParallel, isPresentOnly, isRetainsEntries, isSerial

Field Details

m_extractor

protected ValueExtractor<? super V,? extends Vector<T>> m_extractor

The ValueExtractor to extract the vector from the entry value.

m_vector

protected Vector<T> m_vector

The Vector to extract the vector from the entry value.

m_algorithm

protected DistanceAlgorithm<T> m_algorithm

The DistanceAlgorithm to execute.

m_nMaxResults

protected int m_nMaxResults

The maximum number of results to return.

m_fBruteForce

protected boolean m_fBruteForce

A flag indicating whether to ignore any VectorIndex that may be present and just use the algorithm directly (i.e. use a brute force calculation)

m_filter

protected Filter<?> m_filter

An optional Filter to use to filter the search results.

m_results

protected final transient SortedBag<BinaryQueryResult> m_results

The interim results for the aggregator.

Constructor Details

SimilaritySearch

public SimilaritySearch()

Default constructor for serialization.

SimilaritySearch

public SimilaritySearch(ValueExtractor<? super V,? extends Vector<T>> extractor,
 Vector<T> vector,
 int maxResults)

Create a SimilaritySearch aggregator that will use cosine distance to calculate and return up to maxResults results that are closest to the specified vector.

To use a different distance algorithm, provide it via algorithm(DistanceAlgorithm) method.

You can also specify a filter criteria using filter(Filter) method, and force the aggregator to perform a brute force calculation by calling bruteForce() method. The latter is useful for testing, as it will ignore any available indexes, which allows you to compare the results of an index-based query against the exact matches returned by the brute force search to verify that the recall is where you need it to be, and tune index parameters if it isn't.

Parameters:

extractor - the ValueExtractor to extract the vector from the cache value

vector - the vector to calculate similarity with

maxResults - the maximum number of results to return

Method Details

algorithm

public SimilaritySearch<K,V,T> algorithm(DistanceAlgorithm<T> algorithm)

Set the algorithm to use for distance calculation between vectors.

Parameters:

algorithm - the distance algorithm to use

Returns:

this instance

bruteForce

public SimilaritySearch<K,V,T> bruteForce()

Force brute force search, ignoring any available indexes.

Returns:

this instance

filter

public SimilaritySearch<K,V,T> filter(Filter<?> filter)

Set the filter to use to limit the set of entries to search.

Parameters:

filter - the filter to use

Returns:

this instance

getExtractor

public ValueExtractor<? super V,? extends Vector<T>> getExtractor()

getVector

public Vector<T> getVector()

getAlgorithm

public DistanceAlgorithm<T> getAlgorithm()

getMaxResults

public int getMaxResults()

isBruteForce

public boolean isBruteForce()

getFilter

public Filter<?> getFilter()

characteristics

public int characteristics()

Description copied from interface: InvocableMap.StreamingAggregator

A bit mask representing the set of characteristics of this aggregator.

By default, characteristics are a combination of InvocableMap.StreamingAggregator.PARALLEL and InvocableMap.StreamingAggregator.RETAINS_ENTRIES, which is sub-optimal and should be overridden by the aggregator implementation if the aggregator does not need to retain entries (which is often the case).

Specified by:

characteristics in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Returns:

a bit mask representing the set of characteristics of this aggregator

See Also:

• InvocableMap.StreamingAggregator.ALLOW_INCONSISTENCIES
• InvocableMap.StreamingAggregator.BY_MEMBER
• InvocableMap.StreamingAggregator.BY_PARTITION
• InvocableMap.StreamingAggregator.PARALLEL
• InvocableMap.StreamingAggregator.PRESENT_ONLY
• InvocableMap.StreamingAggregator.RETAINS_ENTRIES
• InvocableMap.StreamingAggregator.SERIAL

supply

public InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>> supply()

Description copied from interface: InvocableMap.StreamingAggregator

Create a new instance of this aggregator.

Specified by:

supply in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Returns:

a StreamAggregator

accumulate

public boolean accumulate(Streamer<? extends InvocableMap.Entry<? extends K,? extends V>> streamer)

Description copied from interface: InvocableMap.StreamingAggregator

Accumulate multiple entries into the result.

Important note: The default implementation of this method provides necessary logic for aggregation short-circuiting and should rarely (if ever) be overridden by the custom aggregator implementation.

Specified by:

accumulate in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Parameters:

streamer - a Streamer that can be used to iterate over entries to add

Returns:

true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

accumulate

public boolean accumulate(InvocableMap.Entry<? extends K,? extends V> entry)

Description copied from interface: InvocableMap.StreamingAggregator

Accumulate one entry into the result.

Specified by:

accumulate in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Parameters:

entry - the entry to accumulate into the aggregation result

Returns:

true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

combine

public boolean combine(List<BinaryQueryResult> partialResult)

Description copied from interface: InvocableMap.StreamingAggregator

Merge another partial result into the result.

Specified by:

combine in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Parameters:

partialResult - the partial result to merge

Returns:

true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

getPartialResult

public List<BinaryQueryResult> getPartialResult()

Description copied from interface: InvocableMap.StreamingAggregator

Return the partial result of the aggregation.

Specified by:

getPartialResult in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Returns:

the partial result of the aggregation

finalizeResult

public List<QueryResult<K,V>> finalizeResult()

Description copied from interface: InvocableMap.StreamingAggregator

Return the final result of the aggregation.

Specified by:

finalizeResult in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Returns:

the final result of the aggregation

finalizeResult

public List<QueryResult<K,V>> finalizeResult(Converter<Binary,?> converterBin)

Description copied from interface: InvocableMap.StreamingAggregator

Return the final result of the aggregation.

This method has a default implementation that simply calls InvocableMap.StreamingAggregator.finalizeResult() in order to avoid compilation errors and preserve backwards compatibility of custom aggregator implementations, even though it would make more sense to do it the other way around if we were designing this API from scratch.

The unfortunate consequence is that even if you override this method in order to use the provided converter, you still need to implement InvocableMap.StreamingAggregator.finalizeResult() method, although you could simply implement it to throw java.lang.UnsupportedOperationException.

Specified by:

finalizeResult in interface InvocableMap.StreamingAggregator<K,V,List<BinaryQueryResult>,List<QueryResult<K,V>>>

Parameters:

converterBin - converter that can be used to convert result from internal format

Returns:

the final result of the aggregation

readExternal

public void readExternal(PofReader in)
                  throws IOException

Description copied from interface: PortableObject

Restore the contents of a user type instance by reading its state using the specified PofReader object.

Specified by:

readExternal in interface PortableObject

Parameters:

in - the PofReader from which to read the object's state

Throws:

IOException - if an I/O error occurs

writeExternal

public void writeExternal(PofWriter out)
                   throws IOException

Description copied from interface: PortableObject

Save the contents of a POF user type instance by writing its state using the specified PofWriter object.

Specified by:

writeExternal in interface PortableObject

Parameters:

out - the PofWriter to which to write the object's state

Throws:

IOException - if an I/O error occurs

readExternal

public void readExternal(DataInput in)
                  throws IOException

Description copied from interface: ExternalizableLite

Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:

readExternal in interface ExternalizableLite

Parameters:

in - the DataInput stream to read data from in order to restore the state of this object

Throws:

IOException - if an I/O exception occurs

writeExternal

public void writeExternal(DataOutput out)
                   throws IOException

Description copied from interface: ExternalizableLite

Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:

writeExternal in interface ExternalizableLite

Parameters:

out - the DataOutput stream to write the state of this object to

Throws:

IOException - if an I/O exception occurs

bruteForce

protected boolean bruteForce(Streamer<? extends InvocableMap.Entry<? extends K,? extends V>> streamer,
 InvocableMap.Entry<? extends K,? extends V> entry)

searchPartition

protected boolean searchPartition(BinaryEntry binaryEntry,
 Vector<T> vector)

If a VectorIndex exists for the specified partition, then use it to perform the KNN search.

Parameters:

binaryEntry - the BinaryEntry to use to identify the partition

vector - the target vector to find the nearest neighbours to

Returns:

true if a VectorIndex was present and used for the search