Documentation
¶
Overview ¶
Package pgvector implements vectorsearch.Index against a PostgreSQL database running the pgvector extension. It uses an existing platform/database.Client for connection management and otelsql instrumentation.
Filter contract: QueryRequest.Filter is interpreted as a string SQL fragment appended to the WHERE clause. Pass it as e.g. "metadata->>'kind' = 'doc'". The fragment is concatenated verbatim — callers are responsible for sanitizing any values they interpolate. Use parameter placeholders ($N) only if you also extend the QueryRequest with a corresponding args slice; the current shape is opaque on purpose.
Index ¶
- Variables
- type Config
- type IndexManager
- func (i *IndexManager[T]) Delete(ctx context.Context, ids ...string) error
- func (i *IndexManager[T]) Query(ctx context.Context, req vectorsearch.QueryRequest) ([]vectorsearch.QueryResult[T], error)
- func (i *IndexManager[T]) Upsert(ctx context.Context, vectors ...vectorsearch.Vector[T]) error
- func (i *IndexManager[T]) Wipe(ctx context.Context) error
- type Option
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidFilter = platformerrors.New("pgvector filter must be a string SQL fragment")
ErrInvalidFilter indicates QueryRequest.Filter was a non-nil value of a type this provider cannot interpret. The pgvector provider only accepts a string SQL fragment; any other type is rejected rather than silently ignored, so a caller that mistakenly passes (for example) a structured filter meant for another provider gets a loud error instead of an unfiltered query that could leak rows across a tenant boundary.
var ErrInvalidIdentifier = platformerrors.New("identifier must match [A-Za-z_][A-Za-z0-9_]*")
ErrInvalidIdentifier indicates an index or column name does not meet the bare-identifier constraint required by this provider.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
MetadataColumn string `env:"METADATA_COLUMN" envDefault:"metadata" json:"metadataColumn,omitempty" yaml:"metadataColumn,omitempty"`
Metric vectorsearch.DistanceMetric `env:"METRIC" envDefault:"cosine" json:"metric,omitempty" yaml:"metric,omitempty"`
Dimension int `env:"DIMENSION" json:"dimension,omitempty" yaml:"dimension,omitempty"`
}
Config configures the pgvector-backed vectorsearch.Index.
Dimension must match the embedding dimension produced by the upstream model and is enforced at index creation time via vector(<Dimension>).
MetadataColumn is the JSONB column used to store the per-vector payload (the generic T type). It defaults to "metadata" and must be a bare identifier.
type IndexManager ¶
type IndexManager[T any] struct { // contains filtered or unexported fields }
IndexManager is the pgvector vectorsearch.Index. It is exported, and returned by NewIndex, so a caller who has chosen pgvector can depend on that choice rather than on the seam every vector index shares.
func NewIndex ¶
func NewIndex[T any]( ctx context.Context, cfg *Config, db database.Client, indexName string, cb circuitbreaking.CircuitBreaker, opts ...Option, ) (*IndexManager[T], error)
NewIndex builds a pgvector-backed vectorsearch.Index. It runs an idempotent schema migration on construction (CREATE EXTENSION + CREATE TABLE + CREATE INDEX) so the table for indexName is guaranteed to exist after the constructor returns.
func (*IndexManager[T]) Delete ¶
func (i *IndexManager[T]) Delete(ctx context.Context, ids ...string) error
Delete implements vectorsearch.Index.
func (*IndexManager[T]) Query ¶
func (i *IndexManager[T]) Query(ctx context.Context, req vectorsearch.QueryRequest) ([]vectorsearch.QueryResult[T], error)
Query implements vectorsearch.Index.
func (*IndexManager[T]) Upsert ¶
func (i *IndexManager[T]) Upsert(ctx context.Context, vectors ...vectorsearch.Vector[T]) error
Upsert implements vectorsearch.Index.
type Option ¶
type Option func(*options)
Option configures the index this package constructs. The zero configuration works: an absent logger logs nowhere, an absent tracer provider traces nowhere, and an absent metrics provider records nothing.
func WithMetricsProvider ¶
WithMetricsProvider attaches a metrics provider for the package's counters and histograms.
func WithTracerProvider ¶
WithTracerProvider attaches a tracer provider, enabling spans on every operation.
Source Files