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" )
const Provider = "PgVector"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
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 Store ¶
type Store struct {
// contains filtered or unexported fields
}
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
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
}
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files