Documentation
¶
Overview ¶
Package pgvector implements Core vector-store capabilities with PostgreSQL's pgvector extension. The host owns the pgx pool. InitializeSchema optionally provisions the extension, schema, four current columns, and selected ANN index.
Current columns are id BYTEA PRIMARY KEY, content TEXT NOT NULL, metadata BYTEA NOT NULL (under MetadataColumn), and embedding VECTOR(N) NOT NULL. Native schema inspection establishes width. Dimensions only seeds a new column. Binary ID equality preserves Core identity; metadata stores complete Core JSON bytes. Recreate former text-ID/JSONB tables and reindex authoritative documents. No compatibility adapter or automatic schema change is provided.
DistanceCosine selects <=>, DistanceL2 selects <->, and DistanceIP selects <#>. IndexHNSW and IndexIVFFlat create native indexes with the selected opclass; IndexNone uses native exact scanning. DistanceMetric is a query choice. It does not override native schema or index configuration.
Core filter.Match selects metadata in a serializable source snapshot. Predicate deletion holds native row locks through commit. Index prepares every vector and commits the whole request atomically; conflicts and native failures are errors. Search ranks selected binary IDs with native distance, validates rows before MinScore, and rejects hybrid mode. Content cannot contain NUL; binary identity and encoded metadata can. These full-source reads favor Core semantics over SQL metadata indexes. See the parent postgres package for shared guarantees.
Native extension contracts: https://github.com/pgvector/pgvector.
Index ¶
- Constants
- type DistanceMetric
- type IndexType
- type Store
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) error
- func (s *Store) DeleteWhere(ctx context.Context, predicate filter.Predicate) error
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) error
- func (s *Store) Search(ctx context.Context, request *vectorstore.SearchRequest) (*vectorstore.SearchResponse, error)
- type StoreConfig
Examples ¶
Constants ¶
const ( DefaultSchemaName = "public" DefaultTableName = "vector_store" DefaultMetadataColumn = "metadata" DefaultIndexSuffix = "_embedding_idx" )
Exported defaults keep constructor behavior visible and overridable.
const Provider = "PgVector"
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric selects the query operator and ANN-index opclass.
const ( // DistanceCosine uses cosine distance (`<=>` and vector_cosine_ops). DistanceCosine DistanceMetric = "cosine" // DistanceL2 uses Euclidean distance (`<->` and vector_l2_ops). DistanceL2 DistanceMetric = "l2" // DistanceIP uses negative inner product (`<#>` and vector_ip_ops). DistanceIP DistanceMetric = "ip" )
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type IndexType ¶
type IndexType string
IndexType selects the ANN index created during schema initialization.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vector-store capabilities with PostgreSQL and pgvector.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
NewStore performs schema setup during construction, which is why it takes a context: a store returned before its backing schema exists would fail on the first index rather than at wiring, where the misconfiguration actually is.
Example ¶
package main
import (
"context"
"os"
"github.com/jackc/pgx/v5/pgxpool"
"github.com/Tangerg/scope/core/document"
"github.com/Tangerg/scope/core/embedding"
"github.com/Tangerg/scope/core/vectorstore"
"github.com/Tangerg/scope/vectorstores/postgres/pgvector"
)
type documentBatcher struct{}
func (d documentBatcher) Batch(_ context.Context, documents []*document.Document) ([][]*document.Document, error) {
return [][]*document.Document{documents}, nil
}
func main() {
ctx := context.Background()
pool, err := pgxpool.New(ctx, os.Getenv("SCOPE_PGVECTOR_DSN"))
if err != nil {
panic(err)
}
defer pool.Close()
model := embedding.ModelFunc(func(_ context.Context, request *embedding.Request) (*embedding.Response, error) {
outputs := make([]*embedding.Output, len(request.Texts))
for index := range outputs {
outputs[index] = &embedding.Output{Embedding: []float64{1, 0}}
}
return embedding.NewResponse(outputs, nil)
})
store, err := pgvector.NewStore(ctx, pgvector.StoreConfig{Pool: pool, SchemaName: "scope", TableName: "documents", EmbeddingModel: model, DocumentBatcher: documentBatcher{}, Dimensions: 2, InitializeSchema: true})
if err != nil {
panic(err)
}
if err = store.Index(ctx, &vectorstore.IndexRequest{Documents: []*document.Document{{ID: "one", Text: "current record"}}}); err != nil {
panic(err)
}
if _, err = store.Search(ctx, &vectorstore.SearchRequest{Query: "current"}); err != nil {
panic(err)
}
if err = store.DeleteIDs(ctx, []string{"one"}); err != nil {
panic(err)
}
}
Output:
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) error
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, request *vectorstore.SearchRequest) (*vectorstore.SearchResponse, error)
type StoreConfig ¶
type StoreConfig struct {
Pool *pgxpool.Pool
SchemaName string
TableName string
IndexName string
MetadataColumn string
EmbeddingModel embedding.Model
DocumentBatcher vectorstore.Batcher
// Dimensions seeds only a newly created native column; existing native width is authoritative.
Dimensions int
DistanceMetric DistanceMetric
IndexType IndexType
InitializeSchema bool
}
StoreConfig names every dependency explicitly rather than defaulting a client or connection, so a store cannot be built against a service the caller did not choose.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files