vectordata

type Collection ¶

type Collection[TKey, TRecord any] interface {
	Searcher[TRecord]

	// Name returns the collection's name.
	Name() string

	// Exists reports whether the collection exists in the store.
	Exists(ctx context.Context) (bool, error)

	// EnsureExists creates the collection if it does not already exist.
	EnsureExists(ctx context.Context) error

	// EnsureDeleted deletes the collection if it exists.
	EnsureDeleted(ctx context.Context) error

	// Get returns the record identified by key, or found=false if the key is
	// missing. It does not create the collection.
	// Use [GetBatch] for native or sequential batch retrieval.
	Get(ctx context.Context, key TKey, options *RecordRetrievalOptions) (TRecord, bool, error)

	// GetFiltered returns up to top records matching filter.
	GetFiltered(ctx context.Context, filter Filter, top int, options *FilteredRecordRetrievalOptions) iter.Seq2[TRecord, error]

	// Delete deletes the record identified by key if it exists. It does not
	// create the collection. Use [DeleteBatch] for native or sequential batch
	// deletion.
	Delete(ctx context.Context, key TKey) error

	// Upsert inserts or updates records as one batch. It accepts individual
	// records or an expanded slice. No records, a nil slice, and an empty slice
	// represent an empty batch. Implementations should generate embeddings once
	// per batch, not once per record. Providers document whether batches are atomic.
	Upsert(ctx context.Context, records ...TRecord) error
}

Collection manages a named collection and its records. Providers document which key, data, vector, filter, and index types they support.

func GetCollection[TKey, TRecord any](s *Store, name string, definition *Definition) (Collection[TKey, TRecord], error)

type DataProperty ¶

type DataProperty struct {
	Name                string
	Type                reflect.Type
	StorageName         string
	ProviderAnnotations map[string]any
	IsIndexed           bool
	IsFullTextIndexed   bool
}

DataProperty describes a stored data field. Indexing and full-text indexing are disabled by default. Type can be inferred from a struct field.

type Definition ¶

type Definition struct {
	Properties         []Property
	EmbeddingGenerator *embedding.BoundGenerator
}

Definition configures the properties stored in a collection. Providers combine it with the record's vectordata tags when constructing a collection handle; they do not modify the caller's definition.

Tags use a role followed by comma-separated settings:

ID     string    `vectordata:"key,autogenerated=false,storage=id"`
Text   string    `vectordata:"data,indexed,fulltext"`
Vector []float32 `vectordata:"vector,dimensions=1536,index=hnsw,distance=cosine_similarity"`

Built-in index and distance names use lowercase snake case. Provider-specific values and storage names retain their casing. Explicit properties override tags, while empty storage, index, and distance names retain tag settings. Dynamic map[string]any records require explicit property types.

EmbeddingGenerator supplies the default generator for vector properties, overriding any store default. A property's generator takes precedence. Use embedding.Bind to configure typed generators; input and output types may differ between vector properties.

type DistanceFunction ¶

type DistanceFunction string

DistanceFunction identifies a vector comparison function. Built-in values use lowercase snake case. Providers may accept additional, case-sensitive values. An empty value uses the provider's default.

const (
	// CosineSimilarity compares vector angles, from -1 (opposite) to 1 (identical).
	CosineSimilarity DistanceFunction = "cosine_similarity"
	// CosineDistance is 1 minus cosine similarity; smaller values are nearer.
	CosineDistance DistanceFunction = "cosine_distance"
	// DotProductSimilarity compares vector lengths and angles; larger is nearer.
	DotProductSimilarity DistanceFunction = "dot_product_similarity"
	// NegativeDotProductSimilarity is negative dot product; smaller is nearer.
	NegativeDotProductSimilarity DistanceFunction = "negative_dot_product_similarity"
	// EuclideanDistance is the L2 distance.
	EuclideanDistance DistanceFunction = "euclidean_distance"
	// EuclideanSquaredDistance is the squared L2 distance.
	EuclideanSquaredDistance DistanceFunction = "euclidean_squared_distance"
	// HammingDistance counts differing coordinates.
	HammingDistance DistanceFunction = "hamming_distance"
	// ManhattanDistance is the sum of absolute coordinate differences.
	ManhattanDistance DistanceFunction = "manhattan_distance"
)

type Error ¶

type Error struct {
	SystemName     string
	StoreName      string
	CollectionName string
	OperationName  string
	Message        string
	Err            error
}

Error describes a vector store failure while preserving the original cause. Provider errors may use it to attach database, collection, and operation names.

func (e *Error) Error() string

func (e *Error) Unwrap() error

type Filter ¶

type Filter struct {
	Operator FilterOperator
	Property string
	Value    any
	Operands []Filter
}

Filter is a provider-translatable predicate over record property names. Comparisons use Property and Value. Equal and NotEqual support nil values. Contains tests whether a collection-valued property contains Value. In tests whether the property's value occurs in a slice or array supplied as Value.

And and Or combine two or more Operands; Not negates a single operand. Logical nodes do not use Property or Value. Providers must return errors for unsupported operations instead of dropping predicates or filtering only after retrieving a limited result set. Filters and values are read-only.

func (f *Filter) Validate() error

type FilterOperator ¶

type FilterOperator string

FilterOperator identifies a portable filter operation. Provider support for individual operations and property types varies.

const (
	Equal              FilterOperator = "eq"
	NotEqual           FilterOperator = "ne"
	GreaterThan        FilterOperator = "gt"
	GreaterThanOrEqual FilterOperator = "ge"
	LessThan           FilterOperator = "lt"
	LessThanOrEqual    FilterOperator = "le"
	Contains           FilterOperator = "contains"
	In                 FilterOperator = "in"
	And                FilterOperator = "and"
	Or                 FilterOperator = "or"
	Not                FilterOperator = "not"
)

type FilteredRecordRetrievalOptions ¶

type FilteredRecordRetrievalOptions struct {
	Skip           int
	OrderBy        []Sort
	IncludeVectors bool
}

FilteredRecordRetrievalOptions controls retrieval by a filter without vector ranking. With no OrderBy, result order is provider-dependent. IncludeVectors defaults to false; provider-specific exceptions may apply.

func (o *FilteredRecordRetrievalOptions) Validate() error

type HybridSearchOptions ¶

type HybridSearchOptions struct {
	Filter             *Filter
	VectorProperty     string
	AdditionalProperty string
	Skip               int
	IncludeVectors     bool
	ScoreThreshold     *float64
}

HybridSearchOptions controls combined vector and keyword search. AdditionalProperty selects a full-text-indexed data property by record name. If empty, the collection must have exactly one such property. ScoreThreshold applies to the provider's combined relevance score.

func (o *HybridSearchOptions) Validate() error

type IndexKind ¶

type IndexKind string

IndexKind identifies a vector index. Built-in values use lowercase snake case. Providers may accept additional, case-sensitive values. An empty value uses the provider's default.

const (
	HNSW          IndexKind = "hnsw"
	Flat          IndexKind = "flat"
	IVFFlat       IndexKind = "ivf_flat"
	DiskANN       IndexKind = "disk_ann"
	QuantizedFlat IndexKind = "quantized_flat"
	Dynamic       IndexKind = "dynamic"
)

type KeyProperty ¶

type KeyProperty struct {
	Name                string
	Type                reflect.Type
	StorageName         string
	ProviderAnnotations map[string]any
	IsAutoGenerated     *bool
}

KeyProperty describes the unique record key. Type can be inferred from a struct field; dynamic records require it explicitly. A nil IsAutoGenerated leaves key generation to the provider's default, distinct from explicit false. StorageName defaults to Name unless the provider reserves a key storage name. ProviderAnnotations are provider-specific.

type KeywordHybridSearcher ¶

type KeywordHybridSearcher[TRecord any] interface {
	// HybridSearch combines vector similarity for searchValue with full-text
	// search for keywords using a full-text-indexed data property. Keywords,
	// search values, and options are read-only. Providers must reject an
	// ambiguous vector or full-text property when no property is selected explicitly.
	HybridSearch(ctx context.Context, searchValue any, keywords []string, top int, options *HybridSearchOptions) iter.Seq2[SearchResult[TRecord], error]
}

KeywordHybridSearcher is an optional capability combining vector similarity with full-text keyword search.

type Property ¶

type Property interface {
	// contains filtered or unexported methods
}

Property describes a key, data, or vector field. Its implementations are *KeyProperty, *DataProperty, and *VectorProperty.

type RecordRetrievalOptions ¶

type RecordRetrievalOptions struct {
	IncludeVectors bool
}

RecordRetrievalOptions controls retrieval of one or more records. IncludeVectors defaults to false, requesting vector exclusion. Providers may document exceptions, such as in-memory storage returning native vectors directly.

type SearchOptions ¶

type SearchOptions struct {
	Filter         *Filter
	VectorProperty string
	Skip           int
	IncludeVectors bool
	ScoreThreshold *float64
}

SearchOptions controls vector search. Property names refer to record fields, not storage names. An empty VectorProperty selects the sole vector property; no vectors or multiple vectors require an explicit selection or an error. A nil Filter does not filter records. Skip defaults to zero.

ScoreThreshold includes scores equal to the threshold. Similarity functions discard lower scores; distance functions discard higher scores. The score range and supported threshold behavior depend on the provider. IncludeVectors defaults to false; provider-specific exceptions may apply.

func (o *SearchOptions) Validate() error

type SearchResult ¶

type SearchResult[TRecord any] struct {
	Record TRecord
	Score  *float64
}

SearchResult contains a matching record and its provider-specific score. A nil Score means the provider did not report a score; zero is a valid score. Similarity scores rank higher values first; distance scores rank lower values first. Scores are not normalized across providers.

type Searcher ¶

type Searcher[TRecord any] interface {
	// Search returns up to top records closest to searchValue, which may be a
	// vector, an embedding, or an input supported by a configured embedding
	// generator. Providers must reject nil search values, nonpositive top,
	// invalid options, and ambiguous vector-property selection rather than
	// selecting a property silently. Filtering happens before ranking, and
	// Skip is applied before taking top.
	Search(ctx context.Context, searchValue any, top int, options *SearchOptions) iter.Seq2[SearchResult[TRecord], error]
}

Searcher performs vector similarity searches. Supported representations and distance functions depend on the provider.

type Sort ¶

type Sort struct {
	Property   string
	Descending bool
}

Sort orders filtered records by a record property. The zero value of Descending requests ascending order. Multiple sorts are applied in slice order.

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store manages collections that may have different key and record types. Create one with NewStore or a database provider's constructor. Use Store.DynamicCollection for map records or GetCollection for typed records. Go 1.27 also supports the generic Collection method.

func NewStore(provider StoreProvider) *Store

func (s *Store) Collection[TKey, TRecord any](name string, definition *Definition) (Collection[TKey, TRecord], error)

func (s *Store) CollectionExists(ctx context.Context, name string) (bool, error)

func (s *Store) DynamicCollection(name string, definition *Definition) (Collection[any, map[string]any], error)

func (s *Store) EnsureCollectionDeleted(ctx context.Context, name string) error

func (s *Store) ListCollectionNames(ctx context.Context) iter.Seq2[string, error]

type StoreProvider ¶

type StoreProvider interface {
	// OpenCollection returns a handle without creating the collection.
	// keyType and recordType describe the caller's Go types. The provider must
	// validate their compatibility with the schema and retain the actual record
	// types across operations; the any parameters are only a dispatch boundary.
	// Optional batch, hybrid-search, and io.Closer capabilities are preserved
	// by the store's typed collection adapters.
	OpenCollection(name string, keyType, recordType reflect.Type, definition *Definition) (Collection[any, any], error)

	ListCollectionNames(ctx context.Context) iter.Seq2[string, error]
	CollectionExists(ctx context.Context, name string) (bool, error)
	EnsureCollectionDeleted(ctx context.Context, name string) error
}

StoreProvider implements the database operations behind a Store. Implementations must support concurrent calls and treat inputs as read-only.

type VectorProperty ¶

type VectorProperty struct {
	Name                string
	Type                reflect.Type
	StorageName         string
	ProviderAnnotations map[string]any
	Dimensions          int
	IndexKind           IndexKind
	DistanceFunction    DistanceFunction
	EmbeddingGenerator  *embedding.BoundGenerator
	EmbeddingType       reflect.Type
}

VectorProperty describes a vector field or input for embedding generation. Dimensions must be positive. IndexKind and DistanceFunction default to the provider's choices. Type can be inferred from a struct field.

EmbeddingGenerator overrides collection defaults; create it with embedding.Bind. For a field supported natively by the provider, an explicit EmbeddingType must match the field type. Its generator may still embed search queries. For other fields, EmbeddingType requests a supported generator output type; an explicit value must match the selected generator's declared output. The field must exactly match the generator's concrete input type or implement its input interface.

Without a generator, an explicit EmbeddingType can describe the output of provider-managed embedding generation. Providers validate supported types and their representation-specific storage requirements.