Documentation
¶
Overview ¶
Package cockroachdb implements Core vector-store capabilities with CockroachDB VECTOR and native VECTOR INDEX over a host-owned pgx pool. CockroachDB v25.4 or newer is required. InitializeSchema optionally creates the current table.
Current columns are id BYTES PRIMARY KEY, content STRING NOT NULL, metadata BYTES NOT NULL (under MetadataColumn), and embedding VECTOR(N) NOT NULL. Native schema inspection owns width; Dimensions only seeds a new column. Binary ID equality preserves Core identity, and metadata contains complete Core JSON bytes. Recreate former string-ID/JSONB tables and reindex authoritative data; no compatibility read or automatic alteration is provided.
DistanceMetric selects a native distance operator and newly created vector index opclass. It does not override native width or an existing index. Core filter.Match alone selects metadata in a serializable source snapshot. Native row locks protect predicate deletion until commit; Index prepares all vectors and commits its whole request atomically. Serialization and native errors remain errors without Scope retries. Search validates native rows before MinScore and rejects hybrid mode. Content cannot contain NUL; binary IDs and encoded metadata can. These full-source reads favor Core semantics over SQL metadata indexes. See the parent postgres package for the shared execution contract.
Index ¶
- Constants
- type DistanceMetric
- 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 = "CockroachDB"
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 both the pgvector-compatible query operator and the native CockroachDB vector-index opclass.
const ( DistanceCosine DistanceMetric = "cosine" DistanceL2 DistanceMetric = "l2" DistanceIP DistanceMetric = "ip" )
The metric is a closed vocabulary because score direction and threshold semantics depend on it: the same raw number means "near" under one metric and "far" under another, so an unrecognized value must be rejected rather than guessed.
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
}
Store implements vector-store capabilities with CockroachDB's native VECTOR type and vector indexes.
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/cockroachdb"
)
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_COCKROACHDB_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 := cockroachdb.NewStore(ctx, cockroachdb.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
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