Documentation
¶
Overview ¶
Package typesense exposes Typesense's semantic and hybrid search through the Core vector-store capability interfaces. Documents are regular Typesense documents in a collection with id / content / metadata (nested object) / embedding (float[]) fields, reached through the official typesense-go v3 client. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Requirements: Typesense 0.25+ (vector search GA) — the store uses nested-object metadata which needs `enable_nested_fields=true` on the collection.
Distance metric: cosine only. Typesense's vector search always uses cosine distance — the result `vector_distance` is in [0, 2] and the store maps it onto a higher-is-better score in [0, 1]. Hybrid search supplies lexical and vector evidence together. Typesense owns the fused ordering; StoreConfig.HybridAlpha optionally controls vector weight, and Scope maps result rank to query-relative relevance.
Schema bootstrap. When StoreConfig.InitializeSchema is true the store probes for the collection and creates it with the right fields + dimensionality if missing. Existing collections are trusted as-is.
Import acknowledgment. Typesense answers the document import endpoint with HTTP 200 even when individual documents were rejected, so the store requires one successful per-document result for every document it sent. A rejected document returns an error while accepted documents in the same batch remain stored.
Filter visitor produces Typesense `filter_by` syntax — `metadata.k:= v`, `metadata.year:>= 2020`, `metadata.tag:= [a,b]` (IN form). The metadata field is a nested object so keys are addressed under the configured prefix.
NOT caveat. Typesense `filter_by` has no top-level NOT operator — the visitor rewrites `NOT (x op y)` into the operator's inverse (e.g. `NOT (year >= 2020)` → `metadata.year:< 2020`). NOT wrapping anything other than a single binary comparison is rejected.
Scoring depends on the vector field's vec_dist. Typesense reports vector_distance without units, and the store reads it as a cosine distance, so InitializeSchema states vec_dist explicitly instead of relying on the provider default and rejects an existing collection that uses "ip" — an inner-product distance read as a cosine one produces plausible scores in the right range that rank results wrongly, which no later call can detect.
Null tests are refused. Typesense has no native filter for a null or missing value; the sanctioned pattern is a companion boolean field written at index time, which this store will not fabricate. filter_by likewise has no pattern-match operator, so LIKE is refused too.
Filterable keys. A metadata key is written into the query language as text, and that language cannot quote a field name, so a filter can only name a key that is a plain identifier. An indexed key is a string literal in the filter DSL, so without that limit a caller's key was read as syntax. A document whose metadata key is anything at all still stores and reads back fine; this is only about which keys a filter can name.
See https://typesense.org/docs/latest/api/vector-search.html.
Index ¶
Constants ¶
const (
DefaultCollectionName = "scope_vector_store"
)
Exported defaults keep constructor behavior visible and overridable.
const Provider = "Typesense"
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vector-store capabilities with Typesense.
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 collection exists would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
Index embeds documents and imports them via the upsert action.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
Search runs semantic vector search or native hybrid search via the documents.Search API.
type StoreConfig ¶
type StoreConfig struct {
// Client is the typesense-go client. Required.
Client *typesense.Client
// CollectionName names the Typesense collection. Optional:
// defaults to [DefaultCollectionName].
CollectionName 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 for a new collection, and is required
// when InitializeSchema is true: the width is part of the field definition,
// and nothing here can read it off a collection that does not exist yet.
Dimensions int
// InitializeSchema, when true, creates the collection with the
// right schema if it doesn't already exist.
InitializeSchema bool
// HybridAlpha controls the vector weight in Typesense's native hybrid
// fusion. Nil preserves the provider default; valid values are [0, 1].
HybridAlpha *float32
}
StoreConfig contains configuration options for the Typesense vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files