AstraDBMemoryStore Class

A memory store that uses Astra database as the backend.

Note: This class is marked as 'experimental' and may change in the future.

Initializes a new instance of the AstraDBMemoryStore class.

Constructor

AstraDBMemoryStore(astra_application_token: str, astra_id: str, astra_region: str, keyspace_name: str, embedding_dim: int, similarity: str, session: ClientSession | None = None, env_file_path: str | None = None, env_file_encoding: str | None = None)

Parameters

Name	Description
astra_application_token Required	str The Astra application token.
astra_id Required	str The Astra id of database.
astra_region Required	str The Astra region
keyspace_name Required	str The Astra keyspace
embedding_dim Required	int The dimensionality to use for new collections.
similarity Required	str TODO
session	Optional session parameter Default value: None
env_file_path	<xref:<xref:semantic_kernel.connectors.memory.astradb.str | None>> Use the environment settings file as a fallback to environment variables. (Optional) Default value: None
env_file_encoding	<xref:<xref:semantic_kernel.connectors.memory.astradb.str | None>> The encoding of the environment settings file. (Optional) Default value: None

Methods

create_collection	Creates a new collection in Astra if it does not exist.
delete_collection	Deletes a collection.
does_collection_exist	Checks if a collection exists.
get	Gets a record. Does not guarantee that the collection exists.
get_batch	Gets a batch of records. Does not guarantee that the collection exists.
get_collections	Gets the list of collections.
get_nearest_match	Gets the nearest match to an embedding using cosine similarity.
get_nearest_matches	Gets the nearest matches to an embedding using cosine similarity.
remove	Removes a memory record from the data store. Does not guarantee that the collection exists.
remove_batch	Removes a batch of records. Does not guarantee that the collection exists.
upsert	Upsert a memory record into the data store. Does not guarantee that the collection exists. If the record already exists, it will be updated. If the record does not exist, it will be created.
upsert_batch	Upsert a batch of memory records into the data store. Does not guarantee that the collection exists. If the record already exists, it will be updated. If the record does not exist, it will be created.

create_collection

Creates a new collection in Astra if it does not exist.

async create_collection(collection_name: str, dimension_num: int | None = None, distance_type: str | None = 'cosine_similarity') -> None

Parameters

Name	Description
collection_name Required	str The name of the collection to create.
dimension_num	int The dimension of the vectors to be stored in this collection. Default value: None
distance_type	str Specifies the similarity metric to be used when querying or comparing vectors within Default value: cosine_similarity
dot_product Required	dot_product (<xref:this collection. The available options are>)
euclidea Required	euclidean
cosine. Required	cosine. (<xref:and>)

Returns

Type	Description
	None

delete_collection

Deletes a collection.

async delete_collection(collection_name: str) -> None

Parameters

Name	Description
collection_name Required	str The name of the collection to delete.

Returns

Type	Description
	None

does_collection_exist

Checks if a collection exists.

async does_collection_exist(collection_name: str) -> bool

Parameters

Name	Description
collection_name Required	str The name of the collection to check.

Returns

Type	Description
bool	True if the collection exists; otherwise, False.

get

Gets a record. Does not guarantee that the collection exists.

async get(collection_name: str, key: str, with_embedding: bool = False) -> MemoryRecord

Parameters

Name	Description
collection_name Required	str The name of the collection to get the record from.
key Required	str The unique database key of the record.
with_embedding	bool Whether to include the embedding in the result. (default: {False}) Default value: False

Returns

Type	Description
MemoryRecord	The record.

get_batch

Gets a batch of records. Does not guarantee that the collection exists.

async get_batch(collection_name: str, keys: list[str], with_embeddings: bool = False) -> list[MemoryRecord]

Parameters

Name	Description
collection_name Required	str The name of the collection to get the records from.
keys Required	<xref:List>[str] The unique database keys of the records.
with_embeddings	bool Whether to include the embeddings in the results. (default: {False}) Default value: False

Returns

Type	Description
List[MemoryRecord]	The records.

get_collections

Gets the list of collections.

async get_collections() -> list[str]

Returns

Type	Description
List[str]	The list of collections.

get_nearest_match

Gets the nearest match to an embedding using cosine similarity.

async get_nearest_match(collection_name: str, embedding: ndarray, min_relevance_score: float = 0.0, with_embedding: bool = False) -> tuple[MemoryRecord, float]

Parameters

Name	Description
collection_name Required	str The name of the collection to get the nearest matches from.
embedding Required	<xref:semantic_kernel.connectors.memory.astradb.ndarray> The embedding to find the nearest matches to.
min_relevance_score	float The minimum relevance score of the matches. (default: {0.0}) Default value: 0.0
with_embedding	bool Whether to include the embeddings in the results. (default: {False}) Default value: False

Returns

Type	Description
Tuple[MemoryRecord, float]	The record and the relevance score.

get_nearest_matches

Gets the nearest matches to an embedding using cosine similarity.

async get_nearest_matches(collection_name: str, embedding: ndarray, limit: int, min_relevance_score: float = 0.0, with_embeddings: bool = False) -> list[tuple[MemoryRecord, float]]

Parameters

Name	Description
collection_name Required	str The name of the collection to get the nearest matches from.
embedding Required	<xref:semantic_kernel.connectors.memory.astradb.ndarray> The embedding to find the nearest matches to.
limit Required	int The maximum number of matches to return.
min_relevance_score	float The minimum relevance score of the matches. (default: {0.0}) Default value: 0.0
with_embeddings	bool Whether to include the embeddings in the results. (default: {False}) Default value: False

Returns

Type	Description
List[Tuple[MemoryRecord, float]]	The records and their relevance scores.

remove

Removes a memory record from the data store. Does not guarantee that the collection exists.

async remove(collection_name: str, key: str) -> None

Parameters

Name	Description
collection_name Required	str The name of the collection to remove the record from.
key Required	str The unique id associated with the memory record to remove.

Returns

Type	Description
	None

remove_batch

Removes a batch of records. Does not guarantee that the collection exists.

async remove_batch(collection_name: str, keys: list[str]) -> None

Parameters

Name	Description
collection_name Required	str The name of the collection to remove the records from.
keys Required	<xref:List>[str] The unique ids associated with the memory records to remove.

Returns

Type	Description
	None

upsert

Upsert a memory record into the data store.

Does not guarantee that the collection exists. If the record already exists, it will be updated. If the record does not exist, it will be created.

async upsert(collection_name: str, record: MemoryRecord) -> str

Parameters

Name	Description
collection_name Required	str The name associated with a collection of embeddings.
record Required	<xref:semantic_kernel.connectors.memory.astradb.MemoryRecord> The memory record to upsert.

Returns

Type	Description
str	The unique identifier for the memory record.

upsert_batch

Upsert a batch of memory records into the data store.

Does not guarantee that the collection exists. If the record already exists, it will be updated. If the record does not exist, it will be created.

async upsert_batch(collection_name: str, records: list[MemoryRecord]) -> list[str]

Parameters

Name	Description
collection_name Required	str The name associated with a collection of embeddings.
records Required	<xref:List>[<xref:MemoryRecord>] The memory records to upsert.

Returns

Type	Description
List[str]	The unique identifiers for the memory record.

Attributes

is_experimental

is_experimental = True

stage_status

stage_status = 'experimental'