README
¶
couchbase
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. 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. See https://docs.couchbase.com/server/current/vector-search/
vector-search.html for the official reference.
Install
go get github.com/Tangerg/scope/vectorstores/couchbase
Constructors
Every constructor validates its config and returns a value implementing
the capability interfaces in core/vectorstore:
NewStore
Testing
This module integrates a third-party service, so its tests cover what runs
without live credentials: config validation, request and response mapping, and
error classification. The shared conformance contract is
core/vectorstore/storetest — this module runs it rather than copying it.
An integration probe skips unless its credential environment variable is set,
so go test ./... is always runnable offline.
Boundaries
This is an independent leaf module: it carries only its own SDK dependency and
never imports a sibling provider. The shared contract every module in this
family obeys is in ../ARCHITECTURE.md.
See ARCHITECTURE.md for what this module owns.
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.
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.
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) Close() error
- 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 )
const Provider = "Couchbase"
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" )
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 (*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. When
// zero and InitializeSchema is true, the store probes EmbeddingModel.
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