llm4s-core
API
Generated with
llm4s-core/org.llm4s/org.llm4s.vectorstore/PgVectorStore

PgVectorStore

org.llm4s.vectorstore.PgVectorStore
See thePgVectorStore companion object
final class PgVectorStore extends VectorStore

PostgreSQL + pgvector implementation of VectorStore.

Uses pgvector extension for efficient vector similarity search with support for IVFFlat and HNSW indexes.

Features:

  • Hardware-accelerated vector operations
  • HNSW indexing for fast approximate nearest neighbor search
  • Connection pooling via HikariCP
  • ACID transactions
  • Scalable to millions of vectors
  • Graceful handling of corrupt embeddings

Corrupt Embedding Handling:

  • Records with unparseable embeddings are skipped during search/query/list operations
  • get() returns None for records with corrupt embeddings
  • Corrupt records are logged with id and embedding_dim for debugging
  • Operations continue successfully with remaining valid records
  • No silent data corruption - failures are observable via logs

Requirements:

  • PostgreSQL 16+ with pgvector extension (18+ recommended)
  • Run: CREATE EXTENSION IF NOT EXISTS vector;

Value parameters

dataSource

HikariCP connection pool

ownsDataSource

Whether to close dataSource on close() (default: true)

tableName

Name of the vectors table

Attributes

Companion
object
Graph
Supertypes
trait VectorStore
class Object
trait Matchable
class Any

Members list

Value members

Concrete methods

override def clear(): Result[Unit]

Clear all records from the store.

Clear all records from the store.

Attributes

Returns

Success or error

Definition Classes
override def close(): Unit

Close the store and release resources.

Close the store and release resources.

Attributes

Definition Classes
override def count(filter: Option[MetadataFilter]): Result[Long]

Count total records in the store.

Count total records in the store.

Value parameters

filter

Optional metadata filter

Attributes

Returns

Record count

Definition Classes
def createHnswIndex(m: Int, efConstruction: Int): Result[Unit]

Create HNSW index for faster similarity search. Call this after bulk loading data for best performance.

Create HNSW index for faster similarity search. Call this after bulk loading data for best performance.

Value parameters

efConstruction

Size of dynamic candidate list (default 64)

m

Maximum number of connections per layer (default 16)

Attributes

override def delete(id: String): Result[Unit]

Delete a record by its ID.

Delete a record by its ID.

Value parameters

id

The record identifier

Attributes

Returns

Success or error

Definition Classes
override def deleteBatch(ids: Seq[String]): Result[Unit]

Delete multiple records by their IDs.

Delete multiple records by their IDs.

Value parameters

ids

The record identifiers

Attributes

Returns

Success or error

Definition Classes
override def deleteByFilter(filter: MetadataFilter): Result[Long]

Delete all records matching a metadata filter.

Delete all records matching a metadata filter.

Value parameters

filter

The metadata filter

Attributes

Returns

Number of records deleted

Definition Classes
override def deleteByPrefix(prefix: String): Result[Long]

Delete all records with IDs starting with the given prefix.

Delete all records with IDs starting with the given prefix.

Value parameters

prefix

The ID prefix to match

Attributes

Returns

Number of records deleted

Definition Classes
override def get(id: String): Result[Option[VectorRecord]]

Retrieve a record by its ID.

Retrieve a record by its ID.

Value parameters

id

The record identifier

Attributes

Returns

The record if found

Definition Classes
override def getBatch(ids: Seq[String]): Result[Seq[VectorRecord]]

Retrieve multiple records by their IDs.

Retrieve multiple records by their IDs.

Value parameters

ids

The record identifiers

Attributes

Returns

The found records (missing IDs are silently skipped)

Definition Classes
override def list(limit: Int, offset: Int, filter: Option[MetadataFilter]): Result[Seq[VectorRecord]]

List records with pagination.

List records with pagination.

Value parameters

filter

Optional metadata filter

limit

Maximum records to return

offset

Number of records to skip

Attributes

Returns

Records in insertion order

Definition Classes
override def search(queryVector: Array[Float], topK: Int, filter: Option[MetadataFilter]): Result[Seq[ScoredRecord]]

Search for the most similar vectors.

Search for the most similar vectors.

Note: if the database contains corrupt embeddings, those rows are silently skipped. Because filtering happens after the SQL LIMIT topK, fewer than topK results may be returned when corrupt rows are present.

Attributes

Definition Classes
override def stats(): Result[VectorStoreStats]

Get statistics about the vector store.

Get statistics about the vector store.

Attributes

Returns

Store statistics

Definition Classes
override def upsert(record: VectorRecord): Result[Unit]

Store a vector record.

Store a vector record.

If a record with the same ID exists, it will be replaced.

Value parameters

record

The record to store

Attributes

Returns

Success or error

Definition Classes
override def upsertBatch(records: Seq[VectorRecord]): Result[Unit]

Store multiple vector records in a batch.

Store multiple vector records in a batch.

More efficient than individual upserts for bulk operations.

Value parameters

records

The records to store

Attributes

Returns

Success or error

Definition Classes

Concrete fields

val tableName: String
Generated with