Interface IVectorStore

Namespace

Mythosia.VectorDb

Assembly

Mythosia.VectorDb.Abstractions.dll

Abstracts vector storage and similarity search operations. Implementations handle only storage and retrieval — they have no knowledge of RAG pipelines.

For logical isolation (e.g. tenant, category), use metadata conditions via Where(string, string).

public interface IVectorStore

Methods

CountAsync(VectorFilter?, CancellationToken)

Returns the number of records matching the optional filter. When filter is null, returns the total record count. Implementations may ignore MinScore as it is not meaningful for counting.

Task<long> CountAsync(VectorFilter? filter = null, CancellationToken cancellationToken = default)

Parameters

filter VectorFilter

cancellationToken CancellationToken

Returns

Task<long>

DeleteAsync(string, VectorFilter?, CancellationToken)

Deletes a single record by its Id. Implementations may use filter to narrow by metadata conditions.

Task DeleteAsync(string id, VectorFilter? filter = null, CancellationToken cancellationToken = default)

Parameters

id string

filter VectorFilter

cancellationToken CancellationToken

Returns

Task

DeleteByFilterAsync(VectorFilter, CancellationToken)

Deletes all records matching the specified filter.

Task DeleteByFilterAsync(VectorFilter filter, CancellationToken cancellationToken = default)

Parameters

filter VectorFilter

cancellationToken CancellationToken

Returns

Task

GetAsync(string, VectorFilter?, CancellationToken)

Retrieves a single record by its Id. Implementations may use filter to narrow results by metadata conditions.

Task<VectorRecord?> GetAsync(string id, VectorFilter? filter = null, CancellationToken cancellationToken = default)

Parameters

id string

filter VectorFilter

cancellationToken CancellationToken

Returns

Task<VectorRecord>

GetBatchAsync(IEnumerable<string>, VectorFilter?, CancellationToken)

Retrieves multiple records by their Ids in a single batch operation. Records that do not exist or do not match filter are omitted from the result. The order of results is not guaranteed to match the order of ids.

Task<IReadOnlyList<VectorRecord>> GetBatchAsync(IEnumerable<string> ids, VectorFilter? filter = null, CancellationToken cancellationToken = default)

Parameters

ids IEnumerable<string>

filter VectorFilter

cancellationToken CancellationToken

Returns

Task<IReadOnlyList<VectorRecord>>

HybridSearchAsync(float[], string, int, VectorFilter?, CancellationToken)

Performs a hybrid search combining dense vector similarity and keyword matching. Implementations with native hybrid support should override this method.

Task<IReadOnlyList<VectorSearchResult>> HybridSearchAsync(float[] denseVector, string query, int topK = 5, VectorFilter? filter = null, CancellationToken cancellationToken = default)

Parameters

denseVector float[]

The dense embedding vector for semantic similarity.

query string

The original text query for keyword-based matching.

topK int

Maximum number of results to return.

filter VectorFilter

Optional filter criteria (metadata conditions, min score).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<VectorSearchResult>>

Results ordered by descending hybrid relevance score.

ReplaceByFilterAsync(VectorFilter, IReadOnlyList<VectorRecord>, CancellationToken)

Atomically replaces all records matching the filter with new records. Deletes existing records by filter, then inserts the new records — both within a single transaction where supported (e.g. PostgreSQL). On failure, the transaction rolls back and existing data remains intact.

Task ReplaceByFilterAsync(VectorFilter filter, IReadOnlyList<VectorRecord> records, CancellationToken cancellationToken = default)

Parameters

filter VectorFilter

Filter identifying the records to delete before inserting.

records IReadOnlyList<VectorRecord>

The new records to insert after deletion.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

SearchAsync(float[], int, VectorFilter?, CancellationToken)

Performs a similarity search. Implementations should respect Conditions and MinScore when present.

Task<IReadOnlyList<VectorSearchResult>> SearchAsync(float[] queryVector, int topK = 5, VectorFilter? filter = null, CancellationToken cancellationToken = default)

Parameters

queryVector float[]

The query embedding vector.

topK int

Maximum number of results to return.

filter VectorFilter

Optional filter criteria (metadata conditions, min score).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<VectorSearchResult>>

Results ordered by descending similarity score.

UpsertAsync(VectorRecord, CancellationToken)

Inserts or updates a single vector record. If a record with the same Id already exists, it is overwritten.

Task UpsertAsync(VectorRecord record, CancellationToken cancellationToken = default)

Parameters

record VectorRecord

cancellationToken CancellationToken

Returns

Task

UpsertBatchAsync(IEnumerable<VectorRecord>, CancellationToken)

Inserts or updates multiple vector records in a batch.

Task UpsertBatchAsync(IEnumerable<VectorRecord> records, CancellationToken cancellationToken = default)

Parameters

records IEnumerable<VectorRecord>

cancellationToken CancellationToken

Returns

Task

VerifyConnectionAsync(CancellationToken)

Verifies that the store can reach its backend (e.g. database, API). Throws on failure. In-memory stores succeed immediately.

Task VerifyConnectionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task