Package com.hazelcast.vector

Interface VectorCollection<K,V>

Type Parameters:
K - key type.
V - value type.
All Superinterfaces:
com.hazelcast.core.DistributedObject
@Beta public interface VectorCollection<K,V> extends com.hazelcast.core.DistributedObject
A mapping of keys to VectorDocuments.

Important note

Key-based operations such as getAsync(Object) or putAsync(Object, VectorDocument) do not use hashCode and equals implementations of key's class. Instead, they use hashCode and equals of the serialized form of the key.

Each mutating operation requires that no optimization process is currently being performed on any index. If any index is undergoing an optimization process, the mutable method will throw an exception IndexMutationDisallowedException. If an index is already undergoing an optimization process, attempting to start a second optimization process on the same index will result an exception IndexMutationDisallowedException. Multiple optimization processes can be performed simultaneously on different indexes.

Since:
5.5

  • Method Summary

    Modifier and Type
    Method
    Description
    CompletionStage<Void>
    clearAsync()
    Asynchronously clears all entries in the vector collection.
    CompletionStage<Void>
    deleteAsync(K key)
    Removes asynchronously the association of given key to a document, if such an association existed.
    CompletionStage<com.hazelcast.vector.VectorDocument<V>>
    getAsync(K key)
    Asynchronously gets the VectorDocument associated with the given key or null if no such association exists.
    static <K, V> VectorCollection<K,V>
    getCollection(com.hazelcast.core.HazelcastInstance instance, com.hazelcast.config.vector.VectorCollectionConfig collectionConfig)
     
    static <K, V> VectorCollection<K,V>
    getCollection(com.hazelcast.core.HazelcastInstance instance, String name)
     
    default CompletionStage<Void>
    optimizeAsync()
    Optimize the only index by fully removing nodes marked for deletion, trimming neighbor sets to the advertised degree, and updating the entry node as necessary.
    CompletionStage<Void>
    optimizeAsync(String indexName)
    Optimize the specified index by fully removing nodes marked for deletion, trimming neighbor sets to the advertised degree, and updating the entry node as necessary.
    CompletionStage<Void>
    putAllAsync(Map<? extends K,com.hazelcast.vector.VectorDocument<V>> documents)
    Inserts asynchronously the given map of key-document pairs.
    CompletionStage<com.hazelcast.vector.VectorDocument<V>>
    putAsync(K key, com.hazelcast.vector.VectorDocument<V> value)
    Asynchronously associates the given key with the value VectorDocument, returning the VectorDocument previously associated with the key if such an association existed.
    CompletionStage<com.hazelcast.vector.VectorDocument<V>>
    putIfAbsentAsync(K key, com.hazelcast.vector.VectorDocument<V> value)
    If the given key is not already associated with a VectorDocument, associates it with the given value and returns null, else returns the current value.
    CompletionStage<com.hazelcast.vector.VectorDocument<V>>
    removeAsync(K key)
    Removes asynchronously the association of given key to a document, if such an association existed, returning the VectorDocument previously associated with the key if such an association existed.
    CompletionStage<SearchResults<K,V>>
    searchAsync(com.hazelcast.vector.VectorValues vectors, com.hazelcast.vector.SearchOptions searchOptions)
    Perform asynchronously a similarity search according to the options in given searchOptions.
    CompletionStage<Void>
    setAsync(K key, com.hazelcast.vector.VectorDocument<V> value)
    Asynchronously associates the given key with the value VectorDocument.
    long
    size()
    Returns the number of values in the vector collection.

    Methods inherited from interface com.hazelcast.core.DistributedObject

    destroy, getDestroyContextForTenant, getName, getPartitionKey, getServiceName

  • Method Details

    • getAsync

      CompletionStage<com.hazelcast.vector.VectorDocument<V>> getAsync(@Nonnull K key)
      Asynchronously gets the VectorDocument associated with the given key or null if no such association exists.
      Parameters:
      key - the key of the entry
      Returns:
      the VectorDocument associated with the given key or null if no such association exists.

    • putAsync

      CompletionStage<com.hazelcast.vector.VectorDocument<V>> putAsync(@Nonnull K key, @Nonnull com.hazelcast.vector.VectorDocument<V> value)
      Asynchronously associates the given key with the value VectorDocument, returning the VectorDocument previously associated with the key if such an association existed.
      Parameters:
      key - the key of the entry
      value - the value to associate the entry with
      Returns:
      the VectorDocument previously associated with key or null if no VectorDocument was previously associated with key.

    • setAsync

      CompletionStage<Void> setAsync(@Nonnull K key, @Nonnull com.hazelcast.vector.VectorDocument<V> value)
      Asynchronously associates the given key with the value VectorDocument.
      Parameters:
      key - the key of the entry
      value - the value to associate the entry with

    • putIfAbsentAsync

      CompletionStage<com.hazelcast.vector.VectorDocument<V>> putIfAbsentAsync(@Nonnull K key, @Nonnull com.hazelcast.vector.VectorDocument<V> value)
      If the given key is not already associated with a VectorDocument, associates it with the given value and returns null, else returns the current value.
      Parameters:
      key - the key of the entry
      value - the value to associate the entry with
      Returns:
      the previous VectorDocument associated with key or null if no such association existed.

    • putAllAsync

      CompletionStage<Void> putAllAsync(Map<? extends K,com.hazelcast.vector.VectorDocument<V>> documents)
      Inserts asynchronously the given map of key-document pairs.
      Parameters:
      documents - a Map of key-document associations to insert in the VectorCollection.

    • removeAsync

      CompletionStage<com.hazelcast.vector.VectorDocument<V>> removeAsync(K key)
      Removes asynchronously the association of given key to a document, if such an association existed, returning the VectorDocument previously associated with the key if such an association existed.
      Parameters:
      key - the key to remove from the VectorCollection
      Returns:
      the VectorDocument previously associated with the given key or null if no such association existed.

    • deleteAsync

      CompletionStage<Void> deleteAsync(K key)
      Removes asynchronously the association of given key to a document, if such an association existed.
      Parameters:
      key - the key to remove from the VectorCollection

    • optimizeAsync

      CompletionStage<Void> optimizeAsync(@Nullable String indexName)
      Optimize the specified index by fully removing nodes marked for deletion, trimming neighbor sets to the advertised degree, and updating the entry node as necessary.

      Backups of this operation are always executed as async backups.

      Parameters:
      indexName - the name of the index to be optimized or null for the only index
      Returns:
      a CompletionStage with a void value if the process finishes successfully; or completed exceptionally with an IndexMutationDisallowedException if the index is currently undergoing an optimization operation; or completed exceptionally with an IllegalArgumentException if index does not exist.

    • optimizeAsync

      default CompletionStage<Void> optimizeAsync()
      Optimize the only index by fully removing nodes marked for deletion, trimming neighbor sets to the advertised degree, and updating the entry node as necessary.

      Backups of this operation are always executed as async backups.

      Returns:
      a CompletionStage with a void value if the process finishes successfully; or completed exceptionally with an IndexMutationDisallowedException if the index is currently undergoing an optimization operation; or completed exceptionally with an IllegalArgumentException if the collection has more than one index.

    • clearAsync

      CompletionStage<Void> clearAsync()
      Asynchronously clears all entries in the vector collection.

      Backups of this operation are always executed as async backups.

      Returns:
      A CompletionStage that completes when the clear operation is finished.

    • size

      long size()
      Returns the number of values in the vector collection.
      Returns:
      the number of values in the vector collection as a long.

    • searchAsync

      CompletionStage<SearchResults<K,V>> searchAsync(com.hazelcast.vector.VectorValues vectors, com.hazelcast.vector.SearchOptions searchOptions)
      Perform asynchronously a similarity search according to the options in given searchOptions.

      If there are many concurrent modifications during search, it is possible but extremely unlikely to receive fewer results than requested, even when the collection contains enough items.

      Parameters:
      vectors - the search vector. Can be unnamed if the collection has only one index, otherwise it has to be associated with index name
      searchOptions - the search options
      Returns:
      SearchResults object that allows to iterate over search results in order of descending similarity score

    • getCollection

      static <K, V> VectorCollection<K,V> getCollection(com.hazelcast.core.HazelcastInstance instance, com.hazelcast.config.vector.VectorCollectionConfig collectionConfig)

    • getCollection

      static <K, V> VectorCollection<K,V> getCollection(com.hazelcast.core.HazelcastInstance instance, String name)