pgvector

Documentation

Overview

Package pgvector provides a memory.Store backed by Postgres with the pgvector extension.

The store uses pgx/v5 as the driver and assumes the target database already has the pgvector extension installed (`CREATE EXTENSION vector` on a recent Postgres). The schema is created on Open and is idempotent across re-opens; the table name is configurable so multiple stores can coexist in the same database without colliding.

Retrieval uses pgvector's cosine distance operator `<=>` (lower is closer); galdor's Score is computed as `1 - distance` so it follows the higher-is-better convention used everywhere else.

The dimensionality of the embeddings is fixed per table at Open time. Adding chunks whose Embedding length differs from the table's declared dimension returns an error rather than silently truncating.

Index

• type Config
• type Store
  • func Open(ctx context.Context, cfg Config) (*Store, error)
  • func (s *Store) Add(ctx context.Context, chunks []memory.Chunk) error
  • func (s *Store) Close() error
  • func (s *Store) Delete(ctx context.Context, documentID string) error
  • func (s *Store) Len(ctx context.Context) (int, error)
  • func (s *Store) Retrieve(ctx context.Context, q memory.Query) ([]memory.Result, error)

Types

type Config

type Config struct {
	// ConnString is a libpq-style connection string accepted by
	// pgxpool.New. Required. Example:
	//   postgres://user:pass@host:5432/db?sslmode=disable
	ConnString string

	// Table is the name of the chunks table. Defaults to "galdor_chunks".
	// Must be a valid Postgres identifier (a-z, 0-9, _) so it can be
	// safely embedded in DDL without quoting.
	Table string

	// Dim is the embedding dimensionality. Required; the table is
	// created with `embedding vector(Dim)` and chunks added later
	// must match.
	Dim int
}

Config configures the pgvector Store.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is a memory.Store backed by Postgres + pgvector. The zero value is not usable; call Open.

func Open

func Open(ctx context.Context, cfg Config) (*Store, error)

Open returns a usable Store. It validates the config, opens a connection pool, ensures the pgvector extension is present and creates the chunks table + indexes if they don't exist.

func (*Store) Add

func (s *Store) Add(ctx context.Context, chunks []memory.Chunk) error

Add ingests chunks. Every chunk must have a non-empty ID; callers are expected to assign stable IDs so re-ingestion is idempotent. Chunks whose Embedding length differs from the table's declared dimension are rejected.

func (*Store) Close

func (s *Store) Close() error

Close releases the connection pool.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, documentID string) error

Delete removes every chunk whose DocumentID matches the argument. Returns nil even when no chunks were removed (idempotent).

func (*Store) Len

func (s *Store) Len(ctx context.Context) (int, error)

Len reports the total number of chunks currently stored. Not part of the Store interface; useful for tests.

func (*Store) Retrieve

func (s *Store) Retrieve(ctx context.Context, q memory.Query) ([]memory.Result, error)

Retrieve runs q against the store. Requires q.Embedding to be set; pure-text queries are rejected because pgvector is a vector store (text-only retrieval belongs in the SQLite/BM25 adapter).

Filtering by metadata maps to JSONB `@>` containment so multi-key filters work in a single round trip.