Help us shape the future of Go! Take the 2026 Go Developer Survey

vector

package
v1.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 22, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

Vector building block (alpha1)

Components implementing the Vector interface in this package back the Dapr Vector building block (dapr/proto/runtime/v1/vector.proto). The contract is portable across dense-vector backends (Meilisearch, Pinecone, Qdrant, Milvus, pgvector, ...).

Lexical / full-text search is a separate building block – see ../search.

See vector.go for the interface and request/response types.

Vector writes reuse the search building block's IndexingOptions, IndexAck and FailedItem types (see ../search/indexing.go).

Contract notes

  • Records are dense only: Record.Values must match the collection's Dimensions. Record.Payload is opaque bytes returned unchanged; Record.Metadata is a structured map[string]any addressed by the portable filter DSL (make, dealer.city, $and/$or/$not, $in, ...).
  • CreateCollection takes typed Dimensions (required) and Metric; DistanceMetricUnspecified selects the component default and a metric the component cannot provide is INVALID_ARGUMENT. An existing collection is ALREADY_EXISTS. GetCollection reports the effective Dimensions and Metric.
  • Delete is a write: it takes IndexingOptions and returns an IndexAck; IDs that do not exist are not an error. Get returns found records in request order.
  • BatchQuery evaluates every query independently and returns one BatchQueryResult{Response|Error} per query in request order. Only request-wide failures (missing collection, credentials, transport) fail the call.
  • Scores are the unnormalized metric value: cosine in [-1, 1] and dot product are higher-is-better, Euclidean is lower-is-better. ScoreThreshold is inclusive on that scale.

Meilisearch (meilisearch/)

  • A collection is a Meilisearch index with one userProvided embedder named default of the requested dimensions; cosine is the only supported metric. Values are stored in _vectors.default, the payload base64-encoded under daprPayload and metadata as the daprMetadata object, which is declared filterable so filter paths translate to daprMetadata.<path>.
  • Collections share the instance with plain indexes, such as those of the search component. ListCollections returns only the indexes that have a userProvided default embedder, and GetCollection, Upsert, Delete and DeleteCollection return FAILED_PRECONDITION for an index without one, including an index whose default embedder generates its vectors.
  • Upsert and Delete require an existing collection and return NOT_FOUND otherwise. Upsert checks first because Meilisearch would create a missing index on the first document addition, without an embedder. The check cannot cover a collection deleted while an upsert is queued, which Meilisearch then recreates without an embedder; as it is no longer a collection, delete it through the search component (DeleteIndex) and call CreateCollection again. A Meilisearch task is atomic, so a record whose Values do not match the collection's dimensions, contain a NaN or infinite value or are all zero, or whose ID is not 1 to 511 bytes of ASCII letters, digits, - and _, is identified before the task is enqueued and reported in FailedItems (INVALID_ARGUMENT). Get omits such an ID like any other missing record.
  • A query vector with a NaN or infinite value or a zero norm is INVALID_ARGUMENT: cosine similarity is undefined for a zero vector, which Meilisearch would otherwise score as a perfect match.
  • A ByID query whose record does not exist is NOT_FOUND; in a BatchQuery only that query fails.
  • Meilisearch's _rankingScore for a pure-semantic query is (1 + cos) / 2; the component reports 2 * rankingScore - 1 and translates a cosine threshold t to rankingScoreThreshold = (1 + t) / 2. A ScoreThreshold outside [-1, 1] is INVALID_ARGUMENT.
  • Meilisearch stores JSON numbers as 64-bit floats, so an integer in record metadata outside ±2^53 comes back rounded, and a filter cannot tell apart values that differ only beyond it. Store such values as strings.
  • Wait-for-completion writes and deletes use the shared task dispatcher of the search component: task status polling by default, the experimental task-change stream when available (see ../search/README.md).

Documentation

Overview

Package vector defines the Vector building-block contract used by Dapr's vector.proto runtime API. Components implement Vector to store, retrieve and query pre-embedded dense vectors.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchQueryRequest 

type BatchQueryRequest struct {
	Collection string
	Queries    []QueryRequest
	Metadata   map[string]string
}

BatchQueryRequest issues multiple queries against the same collection.

type BatchQueryResponse 

type BatchQueryResponse struct {
	Results []BatchQueryResult
}

BatchQueryResponse holds one result per query, in request order.

type BatchQueryResult 

type BatchQueryResult struct {
	Response *QueryResponse
	// Error is a gRPC status error carrying a canonical, non-OK code.
	Error error
}

BatchQueryResult is the outcome of one query in a batch. Exactly one of Response or Error is set.

type CreateCollectionRequest 

type CreateCollectionRequest struct {
	Collection string
	// Component-specific settings such as index parameters.
	Metadata map[string]string
	// Dimensions is the required length of every stored vector.
	Dimensions uint32
	// Metric is the collection's distance metric. Unspecified selects the
	// component's documented default.
	Metric DistanceMetric
}

CreateCollectionRequest creates a new vector collection.

type DeleteCollectionRequest 

type DeleteCollectionRequest struct {
	Collection string
	Metadata   map[string]string
}

DeleteCollectionRequest deletes an existing collection.

type DeleteRequest 

type DeleteRequest struct {
	Collection string
	IDs        []string
	Metadata   map[string]string
	Options    search.IndexingOptions
}

DeleteRequest deletes vectors by id. IDs that do not exist are not an error.

type DeleteResponse 

type DeleteResponse struct {
	// Always IndexAckQueued or IndexAckCompleted on success.
	Ack search.IndexAck
}

DeleteResponse is the result of a Delete call.

type DistanceMetric 

type DistanceMetric int32

DistanceMetric determines how scores and score thresholds are interpreted. Mirrors vector.proto DistanceMetric. 

const (
	// DistanceMetricUnspecified selects the component's default metric on
	// CreateCollection and the collection's configured metric on Query.
	DistanceMetricUnspecified DistanceMetric = 0
	// DistanceMetricCosine is cosine similarity in [-1, 1]. Higher is better.
	DistanceMetricCosine DistanceMetric = 1
	// DistanceMetricDotProduct is unbounded dot-product similarity. Higher is
	// better.
	DistanceMetricDotProduct DistanceMetric = 2
	// DistanceMetricEuclidean is Euclidean distance in [0, +inf). Lower is
	// better.
	DistanceMetricEuclidean DistanceMetric = 3
)

func (DistanceMetric) HigherIsBetter 

func (m DistanceMetric) HigherIsBetter() bool

HigherIsBetter reports whether higher scores indicate closer matches for the metric.

type GetCollectionRequest 

type GetCollectionRequest struct {
	Collection string
	Metadata   map[string]string
}

GetCollectionRequest gets an existing collection.

type GetCollectionResponse 

type GetCollectionResponse struct {
	Collection string
	// Approximate number of records. Providers that cannot supply this value
	// efficiently may return 0.
	RecordCount uint64
	Properties  map[string]string
	Dimensions  uint32
	// Metric is the effective metric and is always concrete.
	Metric DistanceMetric
}

GetCollectionResponse describes an existing collection.

type GetRequest 

type GetRequest struct {
	Collection    string
	IDs           []string
	IncludeValues bool
	Metadata      map[string]string
}

GetRequest fetches vectors by id.

type GetResponse 

type GetResponse struct {
	Records []Record
}

GetResponse is the result of a Get call. Records are returned in request order; records that are not found are omitted.

type ListCollectionsRequest 

type ListCollectionsRequest struct {
	Metadata map[string]string
}

ListCollectionsRequest lists collections in the store.

type ListCollectionsResponse 

type ListCollectionsResponse struct {
	Collections []string
}

ListCollectionsResponse lists collections in the store.

type Match 

type Match struct {
	Record Record
	// Score is the unnormalized value of the effective metric.
	Score float64
}

Match is a single match returned from a vector query.

type Metadata 

type Metadata struct {
	metadata.Base `json:",inline"`
}

Metadata represents a set of vector-component-specific properties.

type QueryRequest 

type QueryRequest struct {
	Collection string
	// Vector is the query vector. Only its Values are read.
	Vector         *Record
	ByID           string
	TopK           uint32
	Filter         map[string]any
	IncludeValues  bool
	IncludePayload bool
	// Metric selects how scores are interpreted. Unspecified uses the
	// collection's configured metric.
	Metric DistanceMetric
	// ScoreThreshold is an inclusive, unnormalized cutoff.
	ScoreThreshold *float64
	Metadata       map[string]string
}

QueryRequest is a single vector query. Exactly one of Vector or ByID is set.

type QueryResponse 

type QueryResponse struct {
	Matches []Match
	// Effective metric used for scores. Always concrete.
	Metric DistanceMetric
}

QueryResponse is the result of a single Query call.

type Record 

type Record struct {
	ID string
	// Values is the dense vector. Its length must equal the collection's
	// dimensions.
	Values []float32
	// Payload is opaque caller data stored with the record and returned
	// unchanged. It is not filterable.
	Payload []byte
	// Metadata holds structured, filterable attributes addressed by the
	// portable filter DSL.
	Metadata map[string]any
}

Record is a single dense vector record.

type UpsertRequest 

type UpsertRequest struct {
	Collection string
	Records    []Record
	Metadata   map[string]string
	Options    search.IndexingOptions
}

UpsertRequest is a keyed upsert of vector records. Every record has a non-empty ID that is unique within the request.

type UpsertResponse 

type UpsertResponse struct {
	// Item-specific failures known at the acknowledgement boundary.
	FailedItems []search.FailedItem
	// Always IndexAckQueued or IndexAckCompleted on success.
	Ack search.IndexAck
}

UpsertResponse is the result of an Upsert call.

type Vector 

type Vector interface {
	metadata.ComponentWithMetadata

	// Init is called once per component instance.
	Init(ctx context.Context, meta Metadata) error

	// Collection lifecycle.
	CreateCollection(ctx context.Context, req *CreateCollectionRequest) error
	GetCollection(ctx context.Context, req *GetCollectionRequest) (*GetCollectionResponse, error)
	ListCollections(ctx context.Context, req *ListCollectionsRequest) (*ListCollectionsResponse, error)
	DeleteCollection(ctx context.Context, req *DeleteCollectionRequest) error

	// Vector data operations.
	Upsert(ctx context.Context, req *UpsertRequest) (*UpsertResponse, error)
	Get(ctx context.Context, req *GetRequest) (*GetResponse, error)
	Delete(ctx context.Context, req *DeleteRequest) (*DeleteResponse, error)

	// Query.
	Query(ctx context.Context, req *QueryRequest) (*QueryResponse, error)
	BatchQuery(ctx context.Context, req *BatchQueryRequest) (*BatchQueryResponse, error)

	io.Closer
}

Vector is the Vector building-block component contract. Method shapes mirror the alpha1 RPCs in dapr/proto/runtime/v1/vector.proto using Go-native types.

Errors returned by components SHOULD be gRPC status errors carrying a canonical code. Other errors are reported to callers as INTERNAL.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.