Asyncio HazelcastClient API (BETA) Documentation

class HazelcastClient(config: Config | None = None, **kwargs)

Bases: object

Hazelcast client instance to access and manipulate distributed data structures on the Hazelcast clusters.

The client can be configured either by:

• providing a configuration object as the first parameter of the constructor

from hazelcast.asyncio import HazelcastClient
from hazelcast.config import Config

config = Config()
config.cluster_name = "a-cluster"
client = await HazelcastClient.create_and_start(config)

• passing configuration options as keyword arguments

from hazelcast.asyncio import HazelcastClient

client = await HazelcastClient.crate_and_start(
    cluster_name="a-cluster",
)

Warning

Asyncio client is not thread-safe, do not access it from other threads.

Warning

Asyncio client is BETA. Its public API may change until General Availability release.

See the hazelcast.config.Config documentation for the possible configuration options.

Creates a HazelcastClient instance.

This call just creates the instance, without starting it.

The preferred way of creating and starting the client instance is using the create_and_start method:

from hazelcast.asyncio import HazelcastClient

client = await HazelcastClient.create_and_start()

See the hazelcast.config.Config documentation for the possible configuration options.

Parameters:

• config – Optional configuration object.

• **kwargs – Optional keyword arguments of the client configuration.

async classmethod create_and_start(config: Config | None = None, **kwargs) → HazelcastClient

Creates a HazelcastClient instance, and starts it.

from hazelcast.asyncio import HazelcastClient

client = await HazelcastClient.create_and_start()

See the hazelcast.config.Config documentation for the possible configuration options.

Parameters:

• config – Optional configuration object.

• **kwargs – Optional keyword arguments of the client configuration.

async get_map(name: str) → Map[KeyType, ValueType]

Returns the distributed map instance with the specified name.

Parameters:

name – Name of the distributed map.

Returns:

Distributed map instance with the specified name.

async create_vector_collection_config(name: str, indexes: List[IndexConfig], backup_count: int = 1, async_backup_count: int = 0, split_brain_protection_name: str | None = None, merge_policy: str = 'PutIfAbsentMergePolicy', merge_batch_size: int = 100) → None

Creates a vector collection with the given configuration.

Parameters:

• name – Name of the distributed map.

• indexes – One or more index configurations. The index names must be unique.

• backup_count – Number of backups to keep for the vector collection.

• split_brain_protection_name – Name of the split brain protection configuration. See https://docs.hazelcast.com/hazelcast/5.6/data-structures/vector-collections#split-brain-protection

• merge_policy – The merge policy to use while recovering in a split brain situation. See https://docs.hazelcast.com/hazelcast/5.6/data-structures/vector-collections#merge-policy

async get_vector_collection(name: str) → VectorCollection

Returns the vector collection instance with the specified name.

Parameters:

name – Name of the vector collection.

Returns:

Vector collection instance with the specified name.

async add_distributed_object_listener(listener_func: Callable[[DistributedObjectEvent], None]) → str

Adds a listener which will be notified when a new distributed object is created or destroyed.

Parameters:

listener_func – Function to be called when a distributed object is created or destroyed.

Returns:

A registration id which is used as a key to remove the listener.

async remove_distributed_object_listener(registration_id: str) → bool

Removes the specified distributed object listener.

Returns silently if there is no such listener added before.

Parameters:

registration_id – The id of the registered listener.

Returns:

True if registration is removed, False otherwise.

async shutdown() → None

Shuts down this HazelcastClient.

property name: str

Name of the client.

property lifecycle_service: LifecycleService

Lifecycle service allows you to check if the client is running and add and remove lifecycle listeners.

property partition_service: PartitionService

Partition service allows you to get partition count, introspect the partition owners, and partition ids of keys.

property cluster_service: ClusterService

Cluster service allows you to get the list of the cluster members and add and remove membership listeners.

Type:

ClusterService

class Map(service_name, name, context)

Bases: Proxy, Generic[KeyType, ValueType]

Hazelcast Map client proxy to access the map on the cluster.

Concurrent, distributed, observable and queryable map.

Example

>>> my_map = await client.get_map("my_map")
>>> print("map.put", await my_map.put("key", "value"))
>>> print("map.contains_key", await my_map.contains_key("key"))
>>> print("map.get", await my_map.get("key"))
>>> print("map.size", await my_map.size())

This class does not allow None to be used as a key or value.

Warning

Asyncio client map proxy is not thread-safe, do not access it from other threads.

Warning

Asyncio client is BETA. Its public API may change until General Availability release.

async add_entry_listener(include_value: bool = False, key: KeyType = None, predicate: Predicate = None, added_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, removed_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, updated_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, evicted_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, evict_all_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, clear_all_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, merged_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, expired_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None, loaded_func: Callable[[EntryEvent[KeyType, ValueType]], None] = None) → str

Adds a continuous entry listener for this map.

Listener will get notified for map events filtered with given parameters.

The listener functions must not block.

Parameters:

• include_value – Whether received event should include the value or not.

• key – Key for filtering the events.

• predicate – Predicate for filtering the events.

• added_func – Function to be called when an entry is added to map.

• removed_func – Function to be called when an entry is removed from map.

• updated_func – Function to be called when an entry is updated.

• evicted_func – Function to be called when an entry is evicted from map.

• evict_all_func – Function to be called when entries are evicted from map.

• clear_all_func – Function to be called when entries are cleared from map.

• merged_func – Function to be called when WAN replicated entry is merged.

• expired_func – Function to be called when an entry’s live time is expired.

• loaded_func – Function to be called when an entry is loaded from a map loader.

Returns:

A registration id which is used as a key to remove the listener.

async add_index(attributes: Sequence[str] = None, index_type: int | str = 0, name: str = None, bitmap_index_options: Dict[str, Any] = None) → None

Adds an index to this map for the specified entries so that queries can run faster.

Example

Let’s say your map values are Employee objects.

>>> class Employee(IdentifiedDataSerializable):
>>>     active = false
>>>     age = None
>>>     name = None
>>>     #other fields
>>>
>>>     #methods

If you query your values mostly based on age and active fields, you should consider indexing these.

>>> employees = await client.get_map("employees")
>>> await employees.add_index(attributes=["age"]) # Sorted index for range queries
>>> await employees.add_index(attributes=["active"], index_type=IndexType.HASH)) # Hash index for equality predicates

Index attribute should either have a getter method or be public. You should also make sure to add the indexes before adding entries to this map.

Indexing time is executed in parallel on each partition by operation threads. The Map is not blocked during this operation. The time taken in proportional to the size of the Map and the number Members.

Until the index finishes being created, any searches for the attribute will use a full Map scan, thus avoiding using a partially built index and returning incorrect results.

Parameters:

• attributes – List of indexed attributes.

• index_type – Type of the index. By default, set to SORTED.

• name – Name of the index.

• bitmap_index_options –

  Bitmap index options.

  • unique_key: (str): The unique key attribute is used as a source of values which uniquely identify each entry being inserted into an index. Defaults to KEY_ATTRIBUTE_NAME. See the hazelcast.config.QueryConstants for possible values.

  • unique_key_transformation (int|str): The transformation is applied to every value extracted from the unique key attribue. Defaults to OBJECT. See the hazelcast.config.UniqueKeyTransformation for possible values.

async add_interceptor(interceptor: Any) → str

Adds an interceptor for this map.

Added interceptor will intercept operations and execute user defined methods.

Parameters:

interceptor – Interceptor for the map which includes user defined methods.

Returns:

Id of registered interceptor.

async aggregate(aggregator: Aggregator[AggregatorResultType], predicate: Predicate = None) → AggregatorResultType

Applies the aggregation logic on map entries and filter the result with the predicate, if given.

Parameters:

• aggregator – Aggregator to aggregate the entries with.

• predicate – Predicate to filter the entries with.

Returns:

The result of the aggregation.

async clear() → None

Clears the map.

The MAP_CLEARED event is fired for any registered listeners.

async contains_key(key: KeyType) → bool

Determines whether this map contains an entry with the key.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

key – The specified key.

Returns:

True if this map contains an entry for the specified key, False otherwise.

async contains_value(value: ValueType) → bool

Determines whether this map contains one or more keys for the specified value.

Parameters:

value – The specified value.

Returns:

True if this map contains an entry for the specified value, False otherwise.

async delete(key: KeyType) → None

Removes the mapping for a key from this map if it is present (optional operation).

Unlike remove(object), this operation does not return the removed value, which avoids the serialization cost of the returned value. If the removed value will not be used, a delete operation is preferred over a remove operation for better performance.

The map will not contain a mapping for the specified key once the call returns.

Warning

This method breaks the contract of EntryListener. When an entry is removed by delete(), it fires an EntryEvent with a None old_value. Also, a listener with predicates will have None values, so only the keys can be queried via predicates.

Parameters:

key – Key of the mapping to be deleted.

async entry_set(predicate: Predicate = None) → List[Tuple[KeyType, ValueType]]

Returns a list clone of the mappings contained in this map.

Warning

The list is NOT backed by the map, so changes to the map are NOT reflected in the list, and vice-versa.

Parameters:

predicate – Predicate for the map to filter entries.

Returns:

The list of key-value tuples in the map.

async evict(key: KeyType) → bool

Evicts the specified key from this map.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

key – Key to evict.

Returns:

True if the key is evicted, False otherwise.

async evict_all() → None

Evicts all keys from this map except the locked ones.

The EVICT_ALL event is fired for any registered listeners.

async execute_on_entries(entry_processor: Any, predicate: Predicate | None = None) → List[Any]

Applies the user defined EntryProcessor to all the entries in the map or entries in the map which satisfies the predicate if provided. Returns the results mapped by each key in the map.

Parameters:

• entry_processor – A stateful serializable object which represents the EntryProcessor defined on server side. This object must have a serializable EntryProcessor counter part registered on server side with the actual com.hazelcast.map.EntryProcessor implementation.

• predicate – Predicate for filtering the entries.

Returns:

List of map entries which includes the keys and the results of the entry process.

async execute_on_key(key: KeyType, entry_processor: Any) → Any

Applies the user defined EntryProcessor to the entry mapped by the key. Returns the object which is the result of EntryProcessor’s process method.

Parameters:

• key – Specified key for the entry to be processed.

• entry_processor – A stateful serializable object which represents the EntryProcessor defined on server side. This object must have a serializable EntryProcessor counter part registered on server side with the actual com.hazelcast.map.EntryProcessor implementation.

Returns:

Result of entry process.

async execute_on_keys(keys: Sequence[KeyType], entry_processor: Any) → List[Any]

Applies the user defined EntryProcessor to the entries mapped by the collection of keys. Returns the results mapped by each key in the collection.

Parameters:

• keys – Collection of the keys for the entries to be processed.

• entry_processor – A stateful serializable object which represents the EntryProcessor defined on server side. This object must have a serializable EntryProcessor counter part registered on server side with the actual com.hazelcast.map.EntryProcessor implementation.

Returns:

List of map entries which includes the keys and the results of the entry process.

async flush() → None

Flushes all the local dirty entries.

async get(key: KeyType) → ValueType | None

Returns the value for the specified key, or None if this map does not contain this key.

Warning

This method returns a clone of original value, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes.

>>> value = await my_map.get(key)
>>> value.update_some_property()
>>> await my_map.put(key,value)

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

key – The specified key.

Returns:

The value for the specified key.

async get_all(keys: Sequence[KeyType]) → Dict[KeyType, ValueType]

Returns the entries for the given keys.

Warning

The returned map is NOT backed by the original map, so changes to the original map are NOT reflected in the returned map, and vice-versa.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

keys – Keys to get.

Returns:

Dictionary of map entries.

async get_entry_view(key: KeyType) → SimpleEntryView[KeyType, ValueType]

Returns the EntryView for the specified key.

Warning

This method returns a clone of original mapping, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

key – The key of the entry.

Returns:

EntryView of the specified key.

async is_empty() → bool

Returns whether this map contains no key-value mappings or not.

Returns:

True if this map contains no key-value mappings, False otherwise.

async key_set(predicate: Predicate | None = None) → List[ValueType]

Returns a List clone of the keys contained in this map or the keys of the entries filtered with the predicate if provided.

Warning

The list is NOT backed by the map, so changes to the map are NOT reflected in the list, and vice-versa.

Parameters:

predicate – Predicate to filter the entries.

Returns:

A list of the clone of the keys.

async load_all(keys: Sequence[KeyType] = None, replace_existing_values: bool = True) → None

Loads all keys from the store at server side or loads the given keys if provided.

Parameters:

• keys – Keys of the entry values to load.

• replace_existing_values – Whether the existing values will be replaced or not with those loaded from the server side MapLoader.

async project(projection: Projection[ProjectionType], predicate: Predicate = None) → ProjectionType

Applies the projection logic on map entries and filter the result with the predicate, if given.

Parameters:

• projection – Projection to project the entries with.

• predicate – Predicate to filter the entries with.

Returns:

The result of the projection.

async put(key: KeyType, value: ValueType, ttl: float = None, max_idle: float = None) → ValueType | None

Associates the specified value with the specified key in this map.

If the map previously contained a mapping for the key, the old value is replaced by the specified value. If ttl is provided, entry will expire and get evicted after the ttl.

Warning

This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – The specified key.

• value – The value to associate with the key.

• ttl – Maximum time in seconds for this entry to stay in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite time-to-live.

• max_idle – Maximum time in seconds for this entry to stay idle in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite max idle time.

Returns:

Previous value associated with key or None if there was no mapping for key.

async put_all(map: Dict[KeyType, ValueType]) → None

Copies all the mappings from the specified map to this map.

No atomicity guarantees are given. In the case of a failure, some key-value tuples may get written, while others are not.

Parameters:

map – Dictionary which includes mappings to be stored in this map.

async put_if_absent(key: KeyType, value: ValueType, ttl: float = None, max_idle: float = None) → ValueType | None

Associates the specified key with the given value if it is not already associated.

If ttl is provided, entry will expire and get evicted after the ttl.

This is equivalent to below, except that the action is performed atomically:

>>> if not (await my_map.contains_key(key)):
>>>     return await my_map.put(key,value)
>>> else:
>>>     return await my_map.get(key)

Warning

This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – Key of the entry.

• value – Value of the entry.

• ttl – Maximum time in seconds for this entry to stay in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite time-to-live.

• max_idle – Maximum time in seconds for this entry to stay idle in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite max idle time.

Returns:

Old value of the entry.

async put_transient(key: KeyType, value: ValueType, ttl: float = None, max_idle: float = None) → None

Same as put, but MapStore defined at the server side will not be called.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – Key of the entry.

• value – Value of the entry.

• ttl – Maximum time in seconds for this entry to stay in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite time-to-live.

• max_idle – Maximum time in seconds for this entry to stay idle in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite max idle time.

async remove(key: KeyType) → ValueType | None

Removes the mapping for a key from this map if it is present.

The map will not contain a mapping for the specified key once the call returns.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

key – Key of the mapping to be deleted.

Returns:

The previous value associated with key, or None if there was no mapping for key.

async remove_all(predicate: Predicate) → None

Removes all entries which match with the supplied predicate.

Parameters:

predicate – Used to select entries to be removed from map.

async remove_if_same(key: KeyType, value: ValueType) → bool

Removes the entry for a key only if it is currently mapped to a given value.

This is equivalent to below, except that the action is performed atomically:

>>> if (await my_map.contains_key(key)) and (await my_map.get(key) == value):
>>>     await my_map.remove(key)
>>>     return True
>>> else:
>>>     return False

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – The specified key.

• value – Remove the key if it has this value.

Returns:

True if the value was removed, False otherwise.

async remove_entry_listener(registration_id: str) → bool

Removes the specified entry listener.

Returns silently if there is no such listener added before.

Parameters:

registration_id – Id of registered listener.

Returns:

True if registration is removed, False otherwise.

async remove_interceptor(registration_id: str) → bool

Removes the given interceptor for this map, so it will not intercept operations anymore.

Parameters:

registration_id – Registration ID of the map interceptor.

Returns:

True if the interceptor is removed, False otherwise.

async replace(key: KeyType, value: ValueType) → ValueType | None

Replaces the entry for a key only if it is currently mapped to some value.

This is equivalent to below, except that the action is performed atomically:

>>> if await my_map.contains_key(key):
>>>     return await my_map.put(key,value)
>>> else:
>>>     return None

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Warning

This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.

Parameters:

• key – The specified key.

• value – The value to replace the previous value.

Returns:

Previous value associated with key, or None if there was no mapping for key.

async replace_if_same(key: ValueType, old_value: ValueType, new_value: ValueType) → bool

Replaces the entry for a key only if it is currently mapped to a given value.

This is equivalent to below, except that the action is performed atomically:

>>> if (await my_map.contains_key(key)) and (await my_map.get(key) == old_value):
>>>     await my_map.put(key, new_value)
>>>     return True
>>> else:
>>>     return False

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – The specified key.

• old_value – Replace the key value if it is the old value.

• new_value – The new value to replace the old value.

Returns:

True if the value was replaced, False otherwise.

async set(key: KeyType, value: ValueType, ttl: float = None, max_idle: float = None) → None

Puts an entry into this map.

Similar to the put operation except that set doesn’t return the old value, which is more efficient. If ttl is provided, entry will expire and get evicted after the ttl.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – Key of the entry.

• value – Value of the entry.

• ttl – Maximum time in seconds for this entry to stay in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite time-to-live.

• max_idle – Maximum time in seconds for this entry to stay idle in the map. If not provided, the value configured on the server side configuration will be used. Setting this to 0 means infinite max idle time.

async set_ttl(key: KeyType, ttl: float) → None

Updates the TTL (time to live) value of the entry specified by the given key with a new TTL value.

New TTL value is valid starting from the time this operation is invoked, not since the time the entry was created. If the entry does not exist or is already expired, this call has no effect.

Parameters:

• key – The key of the map entry.

• ttl – Maximum time in seconds for this entry to stay in the map. Setting this to 0 means infinite time-to-live.

async size() → int

Returns the number of entries in this map.

Returns:

Number of entries in this map.

async try_put(key: KeyType, value: ValueType, timeout: float = 0) → bool

Tries to put the given key and value into this map and returns immediately if timeout is not provided.

If timeout is provided, operation waits until it is completed or timeout is reached.

Parameters:

• key – Key of the entry.

• value – Value of the entry.

• timeout – Maximum time in seconds to wait.

Returns:

True if the put is successful, False otherwise.

async try_remove(key: KeyType, timeout: float = 0) → bool

Tries to remove the given key from this map and returns immediately if timeout is not provided.

If timeout is provided, operation waits until it is completed or timeout is reached.

Parameters:

• key – Key of the entry to be deleted.

• timeout – Maximum time in seconds to wait.

Returns:

True if the remove is successful, False otherwise.

async values(predicate: Predicate = None) → List[ValueType]

Returns a list clone of the values contained in this map or values of the entries which are filtered with the predicate if provided.

Warning

The list is NOT backed by the map, so changes to the map are NOT reflected in the list, and vice-versa.

Parameters:

predicate – Predicate to filter the entries.

Returns:

A list of clone of the values contained in this map.

class VectorCollection(service_name, name, context)

Bases: Proxy, Generic[KeyType, ValueType]

VectorCollection contains documents with vectors.

Concurrent, distributed, observable and searchable vector collection.

The configuration of the vector collection must exist before it can be used.

Example

>>> await client.create_vector_collection_config("my_vc", [
>>>    IndexConfig(name="default-vector", metric=Metric.COSINE, dimension=2)
>>> ]
>>> my_vc = await client.get_vector_collection("my_vc")
>>> await my_vc.set("key1", Vector("default-vector", Type.DENSE, [0.1, 0.2])

Warning

Asyncio client vector collection proxy is not thread-safe, do not access it from other threads.

Warning

Asyncio client is BETA. Its public API may change until General Availability release.

async get(key: Any) → Document | None

Returns the Document for the specified key, or None if this VectorCollection does not contain this key.

Warning

This method returns a clone of the original Document. Modifying the returned Document does not change the actual Document in the VectorCollection. Put the modified Document back to make changes visible to all nodes.

>>> doc = await my_vc.get(key)
>>> doc.value.update_some_property()
>>> await my_vc.set(key, doc)

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in the key’s class.

Parameters:

key – The specified key.

Returns:

The Document for the specified key or None if there was no mapping for key.

async set(key: Any, document: Document) → None

Sets a document for the given key in the VectorCollection.

Similar to the put operation except that set doesn’t return the old document, which is more efficient.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – Key of the entry.

• document – Document of the entry.

async put(key: Any, document: Document) → Document | None

Associates the specified Document with the specified key in this VectorCollection.

If the VectorCollection previously contained a mapping for the key, the old Document is replaced by the specified Document. If the previous value is not needed, using the set method is more efficient.

Warning

This method returns a clone of the previous Document, not the original (identically equal) Document previously put into the VectorCollection.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in the key’s class.

Parameters:

• key – Key of the entry.

• document – Document of the entry.

Returns:

Previous Document associated with the key or None if there was no mapping for the key.

async put_all(map: Dict[Any, Document]) → None

Copies all the mappings from the specified dictionary to this VectorCollection.

No atomicity guarantees are given. In the case of a failure, some key-document tuples may get written, while others are not.

Parameters:

map – Dictionary which includes mappings to be stored in this VectorCollection.

async put_if_absent(key: Any, document: Document) → Document | None

Associates the specified key with the given Document if it is not already associated.

Warning

This method returns a clone of the previous Document, not the original (identically equal) Document previously put into the VectorCollection.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in key’s class.

Parameters:

• key – Key of the entry.

• document – Document of the entry.

Returns:

Old Document for the given key or None if there is not one.

async search_near_vector(vector: Vector, *, include_value: bool = False, include_vectors: bool = False, limit: int = 10, hints: Dict[str, str] = None) → List[SearchResult]

Returns the Documents closest to the given vector.

The search is performed using the distance metric set when creating the vector index.

Parameters:

• vector – The vector to be used as the reference. It must have the same dimension as specified when creating the vector index.

• include_value – Return value attached to the Document.

• include_vectors – Return vectors attached to the Document.

• limit – Limit the maximum number of Documents returned. If not set, 10 is used as the default limit.

Returns:

List of search results.

async remove(key: Any) → Document | None

Removes the mapping for a key from this VectorCollection if it is present (optional operation).

The VectorCollection will not contain a mapping for the specified key once the call returns.

Warning

This method uses __hash__ and __eq__ methods of binary form of the key, not the actual implementations of __hash__ and __eq__ defined in the key’s class.

Parameters:

key – Key of the mapping to be deleted.

Returns:

The Document associated with key, or None if there was no mapping for key.

async delete(key: Any) → None

Removes the mapping for a key from this VectorCollection if it is present (optional operation).

Unlike remove(object), this operation does not return the removed Document, which avoids the serialization cost of the returned Document. If the removed Document will not be used, a delete operation is preferred over a remove operation for better performance.

The VectorCollection will not contain a mapping for the specified key once the call returns.

Parameters:

key – Key of the mapping to be deleted.

async optimize(index_name: str = None) → None

Optimize index by fully removing nodes marked for deletion, trimming neighbor sets to the advertised degree, and updating the entry node as necessary.

Warning

This operation can take a long time to execute and consume a lot of server resources.

Parameters:

index_name – Name of the index to optimize. If not specified, the only index defined for the collection will be used. Must be specified if the collection has more than one index.

async clear() → None

Clears the VectorCollection.

async size() → int

Returns the number of Documents in this VectorCollection.

Returns:

Number of Documents in this VectorCollection.