IEmbeddingStorageService

Namespace: Wisej.AI.Services

Assembly: Wisej.AI

Represents a service for storing and querying embedded documents within specified collections.

C#

public interface IEmbeddingStorageService

VB.NET

Public Interface IEmbeddingStorageService

Methods

ExistsAsync(collectionName, documentName)

Asynchronously checks if a specific document exists within a collection by its name.

Parameter	Type	Description
collectionName	String	The name of the collection to check.
documentName	String	The name of the document to check for existence.

Returns: Task<Boolean>. A boolean indicating whether the document exists in the collection.

This method is used to verify the presence of a document within a collection, useful for conditional operations. Example usage:

  var service = GetEmbeddingStorageService();
  bool exists = await service.ExistsAsync("myCollection", "document1");

Throws:

• ArgumentNullException Thrown if collectionName or documentName is null.

QueryAsync(collectionName, query, topN, minSimilarity, filter)

Asynchronously queries a collection of embedded documents based on a vector query, returning the top K similar documents.

Parameter	Type	Description
collectionName	String	The name of the collection to query.
query	Single[]	The query vector to compare against the stored document embeddings.
topN	Int32	The maximum number of similar documents to return.
minSimilarity	Single	The minimum similarity threshold for the documents to be considered relevant.
filter	Predicate<EmbeddedDocument>	An optional predicate to filter documents before similarity calculation. Defaults to null.

Returns: Task<EmbeddedDocument[]>. An array of EmbeddedDocument that are most similar to the query vector.

This method is used to find documents that are similar to a given vector representation, which is useful in applications such as information retrieval and recommendation systems. Example usage:

  var service = GetEmbeddingStorageService();
  var similarDocuments = await service.QueryAsync("myCollection", new float[] { 0.1f, 0.2f, 0.3f }, 5, 0.8f);

Throws:

• ArgumentNullException Thrown if collectionName or query is null.
• ArgumentException Thrown if topN is less than 1 or minSimilarity is not between 0 and 1.

QueryAsync(collectionName, documentName, query, topN, minSimilarity)

Asynchronously queries for a specific document within a collection based on its name and a query vector.

Parameter	Type	Description
collectionName	String	The name of the collection containing the document.
documentName	String	The name of the document to query.
query	Single[]	The query vector to compare against the document's embedding.
topN	Int32	The maximum number of similar documents to consider.
minSimilarity	Single	The minimum similarity threshold for the document to be considered relevant.

Returns: Task<EmbeddedDocument>. The EmbeddedDocument matching the documentName and meeting the similarity criteria.

This method allows for retrieving specific documents by name and assessing their similarity based on a vector. Example usage:

  var service = GetEmbeddingStorageService();
  var document = await service.QueryAsync("myCollection", "document1", new float[] { 0.1f, 0.2f, 0.3f }, 5, 0.8f);

Throws:

• ArgumentNullException Thrown if collectionName , documentName , or query is null.
• ArgumentException Thrown if topN is less than 1 or minSimilarity is not between 0 and 1.

RemoveAsync(collectionName, filter)

Asynchronously removes documents from a collection that match a specified predicate.

Parameter	Type	Description
collectionName	String	The name of the collection from which documents will be removed.
filter	Predicate<EmbeddedDocument>	An optional predicate to filter documents for removal. Defaults to null.

Returns: Task.

This method is useful for cleaning up documents that meet specific criteria from a collection. If no filter is provided, no action is taken, and the method exits without removing any documents. Example usage:

  var service = GetEmbeddingStorageService();
  await service.RemoveAsync("myCollection", doc => doc.Name.StartsWith("temp"));

Throws:

• ArgumentNullException Thrown if collectionName is null.

RemoveAsync(collectionName, documentName)

Asynchronously removes a specific document from a collection by its name.

Parameter	Type	Description
collectionName	String	The name of the collection from which the document will be removed.
documentName	String	The name of the document to be removed.

Returns: Task.

This method directly targets and removes a document by its name, making it efficient for known documents. Example usage:

  var service = GetEmbeddingStorageService();
  await service.RemoveAsync("myCollection", "document1");

Throws:

• ArgumentNullException Thrown if collectionName or documentName is null.

RetrieveAsync(collectionName, documentName, includeEmbedding)

Asynchronously retrieves a specific document from a collection by its name, with optional inclusion of its embedding.

Parameter	Type	Description
collectionName	String	The name of the collection to retrieve the document from.
documentName	String	The name of the document to retrieve.
includeEmbedding	Boolean	A boolean indicating whether to include the document's embedding in the retrieval.

Returns: Task<EmbeddedDocument>. The EmbeddedDocument that matches the specified document name.

This method fetches a document by its name and optionally includes the embedding data, which can be useful for detailed inspections. Example usage:

  var service = GetEmbeddingStorageService();
  var document = await service.RetrieveAsync("myCollection", "document1", false);

Throws:

• ArgumentNullException Thrown if collectionName or documentName is null.

RetrieveAsync(collectionName, includeEmbedding, filter)

Asynchronously retrieves documents from a collection with optional embedding inclusion and filtering.

Parameter	Type	Description
collectionName	String	The name of the collection to retrieve documents from.
includeEmbedding	Boolean	A boolean indicating whether to include the embeddings of documents in the retrieval.
filter	Predicate<EmbeddedDocument>	An optional predicate to filter documents for retrieval. Defaults to null.

Returns: Task<EmbeddedDocument[]>. An array of EmbeddedDocument that match the specified criteria.

This method retrieves documents from a collection, optionally including their embedding data, and applies an optional filter. Example usage:

  var service = GetEmbeddingStorageService();
  var documents = await service.RetrieveAsync("myCollection", false, doc => doc.Name.Contains("important"));

Throws:

• ArgumentNullException Thrown if collectionName is null.

StoreAsync(collectionName, document)

Asynchronously stores an embedded document within the specified collection.

Parameter	Type	Description
collectionName	String	The name of the collection where the document will be stored.
document	EmbeddedDocument	The embedded document to store.

Returns: Task.

This method is used to persist an embedded document in the specified collection, allowing it to be queried later. Example usage:

  var service = GetEmbeddingStorageService();
  await service.StoreAsync("myCollection", new EmbeddedDocument("newDocument"));

Throws:

• ArgumentNullException Thrown if collectionName or document is null.

Implemented By

Name	Description
AzureAISearchEmbeddingStorageService	Represents a service for storing and querying embeddings using Azure AI Search.
ChromaEmbeddingStorageService	Represents a service for storing and retrieving embeddings using Chroma.
FileSystemEmbeddingStorageService	Provides a file system-based implementation of the IEmbeddingStorageService interface.
MemoryEmbeddingStorageService	Provides an in-memory implementation of the IEmbeddingStorageService interface.
PineconeEmbeddingStorageService	Represents a service for storing and retrieving embeddings using Pinecone.
QdrantEmbeddingStorageService	Represents a service for storing and retrieving embeddings using Qdrant.