Documentation
¶
Overview ¶
Package postgres owns the pgwire vector store shared by the pgvector and cockroachdb backends. Store owns execution, transaction lifetime, and conversion to the Core contracts; each backend's NewStore provisions its native schema and returns that one Store.
The strict current table has exactly four non-null columns with no defaults: binary id as the sole primary key, text content, binary metadata, and a fixed width native vector embedding. Binary identity preserves Core ID bytes without SQL collation or NUL limitations. Binary metadata contains the complete Core JSON encoding; null, an empty object, exact numeric spelling, arbitrary keys, and large exponents survive unchanged. PostgreSQL uses BYTEA; CockroachDB uses BYTES. Content uses native text and cannot contain NUL; Index rejects it before I/O. Metadata may contain encoded NUL values.
NewStore validates the deployed column types, constraints, and vector width. A positive CreateDimensions provisions the current schema when it is missing, never alters an existing table, and requires an existing table to declare that width. Every operation reads the native schema again; no Scope width override advances that fact. Existing text-ID/JSONB tables are rejected. Recreate the table and reindex from authoritative documents; there are no compatibility reads or migrations.
Ordinary Query ranks the supplied vector with native distance and TopK, without enumerating source rows. Opaque binary metadata has no equivalent native predicate here: filters return vectorstore.ErrUnsupportedFilter and FilterDeleter is deliberately not implemented. DeleteIDs is explicit. Host-authorized Scan accepts explicit record, payload-byte, and time budgets. It checks completeness in one read-only transaction before loading records; a budget failure returns no partial matches or invented empty result.
The table carries a named CHECK constraint derived from the bound space ID. Opening an existing table with a different ID is rejected; a missing marker requires rebuilding the table, not labeling its unknown vectors. Reusing an ID for different preprocessing or a different model violates that contract. Validate width and float32 conversion against the current native schema before publication. Upsert batches use one transaction and no model I/O. Loss of a commit acknowledgment leaves all submitted IDs unconfirmed. The Host owns provisioning, the pgx pool, and any decision to reconcile an unknown outcome.
Index ¶
- type DistanceMetric
- func (d DistanceMetric) IndexOpClass() string
- func (d DistanceMetric) Operator() string
- func (d DistanceMetric) Score(value float64) (vectorstore.Score, error)
- func (d DistanceMetric) String() string
- func (d DistanceMetric) Valid() bool
- func (d DistanceMetric) Vector(values []float64, width int) (pgvec.Vector, error)
- type Store
- func (s *Store) CheckDocuments(ctx context.Context, space vectorstore.SpaceID, docs []*document.Document) error
- func (s *Store) CheckQuery(ctx context.Context, space vectorstore.SpaceID, ...) error
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) Query(ctx context.Context, request *vectorstore.Query) (response *vectorstore.SearchResponse, err error)
- func (s *Store) Scan(ctx context.Context, request vectorstore.ScanRequest) (result []*document.Document, err error)
- func (s *Store) Upsert(ctx context.Context, batch *vectorstore.Batch) (err error)
- type StoreConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
const ( DistanceCosine DistanceMetric = "cosine" DistanceL2 DistanceMetric = "l2" DistanceIP DistanceMetric = "ip" )
func (DistanceMetric) IndexOpClass ¶
func (d DistanceMetric) IndexOpClass() string
IndexOpClass returns the native vector index class and panics for an invalid metric.
func (DistanceMetric) Operator ¶
func (d DistanceMetric) Operator() string
Operator returns the pgwire distance operator and panics for an invalid metric.
func (DistanceMetric) Score ¶
func (d DistanceMetric) Score(value float64) (vectorstore.Score, error)
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type Store ¶ added in v0.62.0
type Store struct {
// contains filtered or unexported fields
}
Store executes the Core vector store contracts against one pgwire table; the pgvector and cockroachdb constructors provision its engine-specific schema.
func NewStore ¶ added in v0.62.0
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
func (*Store) CheckDocuments ¶ added in v0.62.0
func (*Store) CheckQuery ¶ added in v0.62.0
func (s *Store) CheckQuery(ctx context.Context, space vectorstore.SpaceID, options vectorstore.SearchOptions) error
Metadata is stored as opaque Core JSON bytes. Without an equivalent native predicate, rejecting the request preserves tenant isolation and global top K.
func (*Store) Query ¶ added in v0.62.0
func (s *Store) Query(ctx context.Context, request *vectorstore.Query) (response *vectorstore.SearchResponse, err error)
func (*Store) Scan ¶ added in v0.62.0
func (s *Store) Scan(ctx context.Context, request vectorstore.ScanRequest) (result []*document.Document, err error)
Scan never returns partial membership. Preflight is performed in the same snapshot as the read, before the client receives any document payload.
type StoreConfig ¶ added in v0.62.0
type StoreConfig struct {
Pool *pgxpool.Pool
SchemaName string
TableName string
MetadataColumn string
Space vectorstore.SpaceID
DistanceMetric DistanceMetric
// CreateDimensions is the facade's provisioning request; the facade creates
// the table, and the engine admits the width it declares.
CreateDimensions vectorstore.CreateDimensions
}
StoreConfig binds an existing table in the strict current schema.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cockroachdb stores and ranks precomputed vectors for an explicitly Host-bound vector space.
|
Package cockroachdb stores and ranks precomputed vectors for an explicitly Host-bound vector space. |
|
Package pgvector stores and ranks precomputed vectors for an explicitly Host-bound vector space.
|
Package pgvector stores and ranks precomputed vectors for an explicitly Host-bound vector space. |