Class PostgresStore

Namespace

Mythosia.VectorDb.Postgres

Assembly

Mythosia.VectorDb.Postgres.dll

PostgreSQL (pgvector) implementation of IVectorStore. Uses a single shared table with a metadata JSONB column for all filtering including logical isolation via metadata conditions.

public class PostgresStore : IVectorStore, IDisposable

Inheritance

object

PostgresStore

Implements

IVectorStore

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

PostgresStore(PostgresOptions)

Creates a new PostgresStore.

public PostgresStore(PostgresOptions options)

Parameters

options PostgresOptions

Configuration options. Validated on construction.

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.

public 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.

public 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.

public Task DeleteByFilterAsync(VectorFilter filter, CancellationToken cancellationToken = default)

Parameters

filter VectorFilter

cancellationToken CancellationToken

Returns

Task

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetAsync(string, VectorFilter?, CancellationToken)

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

public 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.

public 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 with PostgreSQL full-text search (tsvector/tsquery). Both searches run in parallel, then results are merged using Reciprocal Rank Fusion (RRF).

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

Parameters

denseVector float[]

query string

topK int

filter VectorFilter

cancellationToken CancellationToken

Returns

Task<IReadOnlyList<VectorSearchResult>>

ParseVectorString(string)

Parses pgvector text representation '[0.1,0.2,0.3]' back to float[].

public static float[] ParseVectorString(string text)

Parameters

text string

Returns

float[]

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.

public 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?, VectorSearchRuntimeOptions?, CancellationToken)

Performs a similarity search with optional per-request runtime tuning.

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

Parameters

queryVector float[]

topK int

filter VectorFilter

runtimeOptions VectorSearchRuntimeOptions

cancellationToken CancellationToken

Returns

Task<IReadOnlyList<VectorSearchResult>>

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

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

public 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.

public 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.

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

Parameters

records IEnumerable<VectorRecord>

cancellationToken CancellationToken

Returns

Task

VectorToString(float[])

Converts a float array to pgvector literal format: '[0.1,0.2,0.3]'.

public static string VectorToString(float[] values)

Parameters

values float[]

Returns

string

VerifyConnectionAsync(CancellationToken)

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

public Task VerifyConnectionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task