Documentation
¶
Overview ¶
Package couchbase exposes Couchbase Search Service vectors through the Core vector-store capability interfaces. Documents are upserted as JSON (`{id, content, metadata, embedding}`); queries use SQL++ (N1QL) with an embedded `SEARCH(...)` k-NN clause that targets a Couchbase FTS index. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Requirements: Couchbase Server 7.6+ — that's when the Search Service learned to index dense vectors and answer KNN queries. The store talks to the cluster over gocb v2.
Similarity functions: SimilarityCosine / SimilarityL2Norm / SimilarityDotProduct. Default is dot product (matches the the framework defaults); pick cosine if your embedder isn't normalised.
Index optimization knobs: OptimizeRecall (default), OptimizeLatency, OptimizeMemory — they hint Couchbase how to trade recall against latency / memory at index build time.
Filter visitor produces SQL++ predicates under the `metadata.*` path; each segment is backtick-quoted so reserved chars / keywords pass through. Vectors are inlined into the SQL as JSON arrays — gocb's standard parameter binding doesn't yet carry a typed vector shape, but the value is a plain number array so it's safe.
Schema. The store provisions an FTS index of type `vectorSearch` under StoreConfig.InitializeSchema = true, mirroring the JSON template the framework ships.
Writes. Couchbase's KV service upserts one document per call, so Index applies a batch document by document and a failure partway leaves the documents before it stored. No durability level is requested, which is Couchbase's own recommendation — "durability is a useful feature but should not be the default for most applications" — so a mutation is acknowledged once the active node holds it, and a node failure before replication can lose it. Both are the provider's shape rather than a choice made here; the error names the document the batch stopped on.
Statement results. gocb reports a failure raised while a query result streams through Err and Close, not from the initial call, so every statement the store runs — searches and filtered deletion alike — goes through one owner that iterates, checks the stream, and closes the result. A statement that failed mid-stream is an error even though its first response succeeded.
Absent keys. SQL++ says "if either operand in a comparison is MISSING, the result is MISSING", which drops the document for any operator and stays MISSING under NOT. The filter AST is two-valued — an absent key evaluates as nil and every comparison against it is decided — so each leaf carries the truth value the AST assigns: `<path> IS NOT VALUED OR ...` for !=, `<path> IS VALUED AND ...` for the rest. IS NULL tests emit IS NOT VALUED, because SQL++ IS NULL requires an explicit NULL and does not match a MISSING path, which is what an absent metadata key is.
Scores. Couchbase publishes no formula for the Search Service relevance score, for any of its similarity metrics, and the score is not confined to Core's range: the documented example response for a vector query returns 3.4028234663852886e+38 — float32's maximum — next to 0.42046520427629075. The store maps the score rather than clamping it, and claims only the ordering Couchbase ranked by, which is all the documentation supports. Clamping had made an exact match and a mediocre one the same number and left MinScore unable to tell them apart.
See https://docs.couchbase.com/server/current/vector-search/ vector-search.html for the official reference.
Index ¶
- Constants
- type IndexOptimization
- type Similarity
- type Store
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
- func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
- type StoreConfig
Constants ¶
const ( DefaultScopeName = "_default" DefaultCollectionName = "_default" DefaultIndexName = "scope-vector-index" DefaultSimilarity = SimilarityDotProduct DefaultIndexOptimize = OptimizeRecall )
Exported defaults keep constructor behavior visible and overridable.
const Provider = "Couchbase"
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type IndexOptimization ¶
type IndexOptimization string
IndexOptimization picks the tradeoff for Couchbase's vector index: recall (default), latency, or memory.
const ( OptimizeRecall IndexOptimization = "recall" OptimizeLatency IndexOptimization = "latency" OptimizeMemory IndexOptimization = "memory" )
These are the provider values this adapter recognizes.
func (IndexOptimization) String ¶
func (i IndexOptimization) String() string
func (IndexOptimization) Valid ¶
func (i IndexOptimization) Valid() bool
type Similarity ¶
type Similarity string
Similarity selects the vector similarity function written into the Couchbase search-index definition.
const ( // SimilarityCosine — cosine similarity. SimilarityCosine Similarity = "cosine" // SimilarityL2Norm — L2 (Euclidean) norm. SimilarityL2Norm Similarity = "l2_norm" // SimilarityDotProduct — dot product. Default; works // best with already-normalized embeddings (e.g. OpenAI). SimilarityDotProduct Similarity = "dot_product" )
func (Similarity) String ¶
func (s Similarity) String() string
func (Similarity) Valid ¶
func (s Similarity) Valid() bool
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vector-store capabilities with Couchbase Search Service.
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 scope, collection, and search index exist would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteIDs ¶
DeleteIDs removes documents by their KV key. Index upserts each document under its id as the document key (see Store.Index), so the id is the KV key here too. An empty slice is a no-op; a per-key "document not found" error is treated as success so repeated deletes stay idempotent. Implements vectorstore.IDDeleter.
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
Index embeds documents and upserts them by id.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
Search runs a SQL++ query that embeds the KNN search clause.
type StoreConfig ¶
type StoreConfig struct {
// Cluster is the connected gocb cluster. Required.
Cluster *gocb.Cluster
// BucketName is the Couchbase bucket. Required.
BucketName string
// ScopeName is the scope within the bucket. Optional: defaults
// to [DefaultScopeName] ("_default").
ScopeName string
// CollectionName is the collection within the scope. Optional:
// defaults to [DefaultCollectionName] ("_default").
CollectionName string
// VectorIndexName is the search-index name. Optional: defaults
// to [DefaultIndexName].
VectorIndexName string
// EmbeddingModel produces vectors for the documents. Required.
EmbeddingModel embedding.Model
// DocumentBatcher batches documents before upsert. Required.
DocumentBatcher vectorstore.Batcher
// Dimensions sets the vector width registered with the search index, and is
// required when InitializeSchema is true: the width is part of the index
// definition, and nothing here can read it off an index that does not exist
// yet.
Dimensions int
// Similarity selects the vector similarity function. Optional:
// defaults to [SimilarityDotProduct].
Similarity Similarity
// IndexOptimization selects recall / latency / memory tradeoff.
// Optional: defaults to [OptimizeRecall].
IndexOptimization IndexOptimization
// InitializeSchema, when true, creates the search index if it
// doesn't already exist.
InitializeSchema bool
}
StoreConfig contains configuration options for the Couchbase Search vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files