Documentation
¶
Overview ¶
Package pgvector provides a PostgreSQL pgvector-backed VectorStore implementation.
pgvector is a PostgreSQL extension for vector similarity search. This implementation supports all core VectorStore operations including namespaced storage, metadata filtering, and index management.
Setup ¶
Start PostgreSQL with pgvector using Docker:
docker run -p 5432:5432 -e POSTGRES_PASSWORD=password pgvector/pgvector:pg17
Basic Usage ¶
store, err := pgvector.New(ctx, "postgres://user:pass@localhost:5432/db",
pgvector.WithTableName("documents"),
pgvector.WithDimensions(1536),
)
if err != nil {
log.Fatal(err)
}
defer store.Close()
// Add documents
err = store.Add(ctx, []vectorstore.Document{
{ID: "1", Content: "Hello", Embedding: vec1},
{ID: "2", Content: "World", Embedding: vec2},
})
// Search
results, err := store.Search(ctx, queryVec, vectorstore.SearchOptions{K: 5})
Index Management ¶
The pgvector store implements the Indexer interface:
// Create a table with vector column err := store.CreateIndex(ctx, "products", 768, embedding.Cosine) // List tables tables, err := store.ListIndexes(ctx) // Delete a table err := store.DeleteIndex(ctx, "products")
Testing ¶
For testing, use testcontainers to spin up a PostgreSQL instance:
import "github.com/testcontainers/testcontainers-go/modules/postgres"
container, _ := postgres.Run(ctx, "pgvector/pgvector:pg17",
postgres.WithDatabase("testdb"),
postgres.WithUsername("test"),
postgres.WithPassword("test"),
)
connStr, _ := container.ConnectionString(ctx)
store, _ := New(ctx, connStr)
Index ¶
- type Option
- type Options
- type Pool
- type Store
- func (s *Store) Add(ctx context.Context, docs []vectorstore.Document, ...) error
- func (s *Store) Close() error
- func (s *Store) CreateIndex(ctx context.Context, name string, dims int, metric embedding.Metric) error
- func (s *Store) Delete(ctx context.Context, ids []string, namespace string) error
- func (s *Store) DeleteIndex(ctx context.Context, name string) error
- func (s *Store) ListIndexes(ctx context.Context) ([]string, error)
- func (s *Store) Search(ctx context.Context, queryEmbedding embedding.Vector, ...) ([]vectorstore.Document, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*Options)
Option configures a Store.
func WithAutoCreateTable ¶
WithAutoCreateTable enables automatic table creation.
func WithDimensions ¶
WithDimensions sets the vector dimensions.
func WithMetric ¶
WithMetric sets the distance metric.
func WithTableName ¶
WithTableName sets the default table name.
type Options ¶
type Options struct {
// TableName is the default table to use. Default: "documents"
TableName string
// Dimensions is the vector dimensionality. Required for table creation.
Dimensions int
// Metric specifies the distance metric. Default: Cosine
Metric embedding.Metric
// AutoCreateTable creates the table if it doesn't exist.
AutoCreateTable bool
}
Options configures the pgvector store.
type Pool ¶
type Pool interface {
Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
Close()
}
Pool defines the interface for PostgreSQL pool operations.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a pgvector-backed VectorStore implementation.
func NewFromPool ¶
NewFromPool creates a new pgvector vector store with the provided pool.
func (*Store) Add ¶
func (s *Store) Add(ctx context.Context, docs []vectorstore.Document, optFns ...func(*vectorstore.AddOptions)) error
Add inserts or updates documents in the store.
func (*Store) CreateIndex ¶
func (s *Store) CreateIndex(ctx context.Context, name string, dims int, metric embedding.Metric) error
CreateIndex creates a new table with vector column.
func (*Store) DeleteIndex ¶
DeleteIndex removes a table and all its data.
func (*Store) ListIndexes ¶
ListIndexes returns all tables with vector columns.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, queryEmbedding embedding.Vector, opts vectorstore.SearchOptions) ([]vectorstore.Document, error)
Search finds documents similar to the query embedding.
Source Files