Documentation
¶
Overview ¶
Package mongodb stores prepared vectors in a host-owned MongoDB Vector Search collection. The Host provisions and owns the driver, collection and indexes. NewStore and each data operation read the named READY, queryable vectorSearch definition. Its one vector field must be SpaceID.StorageKey(); a different space of the same dimension cannot bind the index. The native definition supplies the width and similarity policy, and must index _id as a filter.
Upsert validates every FLOAT32 vector before submitting one ordered BulkWrite. The bound metric also governs query and stored vectors: cosine rejects zero magnitude; dotProduct requires unit length within one FLOAT32 ULP at one. Vectors are never normalized because preprocessing belongs to the Host's space. Replacements require both the string _id and the space-specific vector field. A conflicting identity in another space cannot overwrite that record. Uncertain delivery, rejected writes and ordered unattempted tails remain distinguishable through vectorstore.WriteError. An acknowledged write does not guarantee visibility in the asynchronous vector index. No operation embeds text.
Core metadata is stored losslessly in metadata_json. metadata_terms is an atomic derived projection of those bytes. Query uses native vector ranking; scalar top-level string equality requires metadata_terms in the vector index. Unsupported filters fail without enumerating documents. DeleteWhere uses an indexed term under binary collation and requires a matching ordinary ascending metadata_terms index; its hint prevents a silent full collection scan.
QueryByScan and DeleteMatching are explicit alternatives for arbitrary Core predicates. Their budget covers source BSON bytes and records, including nonmatches, and elapsed time. Server aggregation admits at most MaxRecords+1 candidates and withholds payloads beyond the grant. Budget exhaustion returns no partial search result and happens before any delete. The ranking pass validates current metadata; conditional deletion compares observed metadata under binary collation. The separate selection and action have no shared snapshot. Identical metadata does not prove a record revision, and concurrent new matches may be missed.
Ordinary tests are offline. Integration tests require SCOPE_MONGODB_URI on a deployment with Vector Search; fixtures provision and remove isolated databases.
Index ¶
- Constants
- type DocumentCollection
- 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, opts vectorstore.SearchOptions) error
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) error
- func (s *Store) DeleteMatching(ctx context.Context, predicate filter.Predicate, budget vectorstore.ScanBudget) error
- func (s *Store) DeleteWhere(ctx context.Context, predicate filter.Predicate) error
- func (s *Store) Query(ctx context.Context, q *vectorstore.Query) (*vectorstore.SearchResponse, error)
- func (s *Store) QueryByScan(ctx context.Context, q *vectorstore.Query, budget vectorstore.ScanBudget) (*vectorstore.SearchResponse, error)
- func (s *Store) Upsert(ctx context.Context, batch *vectorstore.Batch) error
- type StoreConfig
Examples ¶
Constants ¶
const ( Provider = "MongoDB" DefaultVectorIndexName = "vector_index" DefaultNumCandidates = 200 MaxNumCandidates = 10000 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DocumentCollection ¶ added in v0.16.0
type DocumentCollection interface {
BulkWrite(context.Context, []mongo.WriteModel, ...options.Lister[options.BulkWriteOptions]) (*mongo.BulkWriteResult, error)
Aggregate(context.Context, any, ...options.Lister[options.AggregateOptions]) (*mongo.Cursor, error)
DeleteMany(context.Context, any, ...options.Lister[options.DeleteManyOptions]) (*mongo.DeleteResult, error)
}
DocumentCollection contains native data-plane operations. The host owns the collection, native client, credentials, index provisioning and lifecycle.
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"
"time"
"go.mongodb.org/mongo-driver/v2/mongo"
"go.mongodb.org/mongo-driver/v2/mongo/options"
"github.com/Tangerg/scope/core/document"
"github.com/Tangerg/scope/core/vectorstore"
"github.com/Tangerg/scope/vectorstores/mongodb"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
client, err := mongo.Connect(options.Client().ApplyURI("mongodb://localhost:27017/?directConnection=true"))
if err != nil {
panic(err)
}
defer func() {
if closeErr := client.Disconnect(context.WithoutCancel(ctx)); closeErr != nil {
panic(closeErr)
}
}()
// The host has provisioned this collection and a READY native vector index.
store, err := mongodb.NewStore(ctx, mongodb.StoreConfig{Collection: client.Database("scope").Collection("documents"), VectorIndexName: "vector_index", Space: "example-v1"})
if err != nil {
panic(err)
}
if err = store.Upsert(ctx, &vectorstore.Batch{Space: "example-v1", Records: []vectorstore.Record{{Document: &document.Document{ID: "one", Text: "hello"}, Values: []float64{1, 0}}}}); err != nil {
panic(err)
}
if _, err = store.Query(ctx, &vectorstore.Query{Space: "example-v1", Values: []float64{1, 0}}); err != nil {
panic(err)
}
if err = store.DeleteIDs(ctx, []string{"one"}); err != nil {
panic(err)
}
}
Output:
func (*Store) CheckDocuments ¶ added in v0.59.0
func (*Store) CheckQuery ¶ added in v0.59.0
func (s *Store) CheckQuery(ctx context.Context, space vectorstore.SpaceID, opts vectorstore.SearchOptions) error
func (*Store) DeleteMatching ¶ added in v0.59.0
func (s *Store) DeleteMatching(ctx context.Context, predicate filter.Predicate, budget vectorstore.ScanBudget) error
func (*Store) DeleteWhere ¶
func (*Store) Query ¶ added in v0.59.0
func (s *Store) Query(ctx context.Context, q *vectorstore.Query) (*vectorstore.SearchResponse, error)
func (*Store) QueryByScan ¶ added in v0.60.0
func (s *Store) QueryByScan(ctx context.Context, q *vectorstore.Query, budget vectorstore.ScanBudget) (*vectorstore.SearchResponse, error)
type StoreConfig ¶
type StoreConfig struct {
Collection DocumentCollection
VectorIndexName string
Space vectorstore.SpaceID
// NumCandidates is the native ANN recall floor, raised to cover TopK.
NumCandidates int
}
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files