Documentation
¶
Overview ¶
Package weaviate exposes Weaviate through the Core vector-store capability interfaces. Documents are stored as objects in a Weaviate class (`{id, vector, properties}`). Semantic retrieval runs `nearVector`; hybrid retrieval combines the supplied vector with lexical evidence from `content` through relative-score fusion. StoreConfig.HybridAlpha optionally controls vector weight. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Requirements: a reachable Weaviate v5 server (self-hosted or Weaviate Cloud Services). The store uses the official weaviate-go-client/v5.
Vector similarity functions: cosine / dot / l2-squared / hamming / manhattan. The chosen value is bound to the class's vector index config at creation time.
Schema. Weaviate is strongly typed — properties participating in filters must be declared at class-creation time. StoreConfig enumerates these properties so the store can issue a CREATE CLASS when needed.
Filter visitor produces Weaviate's `where` filter operator tree — `{"operator": "Equal", "path": ["author"], "valueText": "..."}`, `{"operator": "And", "operands": [...]}`, `{"operator": "GreaterThan", "valueNumber": 100}`. The result feeds the `WithWhere` builder on the GraphQL Get call.
Batch acknowledgment. Weaviate answers a batch whose objects individually failed with a successful call, so Index requires one SUCCESS result per object it sent. A rejected object returns an error while the objects accepted in the same batch remain stored.
Metadata filtering needs declared properties. Weaviate classes are typed and a where filter may only name a declared property, so StoreConfig.MetadataProperties enumerates the keys filters may select on. Each becomes a class property under InitializeSchema and is written alongside the document; the complete metadata map is also stored as JSON so every key round-trips losslessly whether or not it is filterable. A filter naming an undeclared key is refused, because a path with no matching field is not a narrower query but one the server cannot answer.
A declared text property pins field tokenization, which "treats the entire value of the property as a single token" and "preserves both case and symbols". Weaviate's default word tokenization splits on non-alphanumeric characters and lowercases each token, which would make equality a token match rather than the whole-value, case-sensitive comparison a filter asks for. The content property keeps word tokenization, which is what hybrid search needs.
A nested metadata key cannot be filtered: it would need an object property with declared nestedProperties, and dotted-path filtering on those leaves is a Weaviate v1.38 preview feature.
Filtered deletion repeats. One batch delete removes at most QUERY_MAXIMUM_RESULTS objects — the response calls Successful the count "in this round" — and Weaviate's guidance for a filter that matches more is to re-run the query, so DeleteWhere does until the round deletes everything it matched. Objects that could not be deleted are reported in Failed rather than as a call error, so that count is checked too; a round that matches more than it deletes while deleting nothing is refused instead of repeated, since it cannot progress.
Existing class. The class is verified whenever it is found, whatever InitializeSchema says, because that flag answers whether a missing class may be created and not whether the one found is the right one — and the second question matters most for a class provisioned out of band. A class that is neither found nor creatable fails construction rather than every later request. Existence was previously taken for agreement: search converts Weaviate's distance into a Score using the configured metric, so a class built with l2-squared while the config says cosine returned scores that were wrong rather than absent. A mismatch now fails construction with ErrIncompatibleClass. Only the distance is compared — a class whose vectorizer is none declares no vector width, so there is no dimension on it to disagree with.
See https://weaviate.io/developers/weaviate for the full API surface.
Index ¶
- Constants
- Variables
- type DistanceMetric
- type MetadataProperty
- 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 MetadataDataText = "text"
MetadataDataText is the data type whose tokenization the store pins. Filters compare whole values case-sensitively, and Weaviate's default word tokenization "splits text by any non-alphanumeric characters, then lowercases each token" — field tokenization instead "treats the entire value of the property as a single token" and "preserves both case and symbols".
const (
Provider = "Weaviate"
)
Provider is the stable backend name for host-side attribution.
Variables ¶
var ( ErrMissingClient = errors.New("weaviate: Client is required") ErrMissingClassName = errors.New("weaviate: ClassName is required") ErrMissingEmbeddingModel = errors.New("weaviate: EmbeddingModel is required") ErrMissingDocumentBatcher = errors.New("weaviate: DocumentBatcher is required") ErrInvalidObjectID = errors.New("weaviate: invalid object ID") ErrIncompatibleClass = errors.New("weaviate: existing class is incompatible") )
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric selects the distance function configured on the Weaviate collection.
const ( DistanceCosine DistanceMetric = "cosine" DistanceDot DistanceMetric = "dot" DistanceL2Squared DistanceMetric = "l2-squared" DistanceHamming DistanceMetric = "hamming" DistanceManhattan DistanceMetric = "manhattan" )
The metric is a closed vocabulary because score direction and threshold semantics depend on it: the same raw number means "near" under one metric and "far" under another, so an unrecognized value must be rejected rather than guessed.
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type MetadataProperty ¶ added in v0.16.0
type MetadataProperty struct {
// Name is the metadata key, used verbatim as the property name.
Name string
// DataType is the Weaviate data type: "text", "int", "number",
// "boolean", or "date".
DataType string
}
MetadataProperty declares one metadata key as a class property so filters can select on it.
Weaviate classes are typed and a where filter may only name a declared property, so the filterable keys have to be known when the class is created — the same constraint cassandra, milvus, and mongodb answer with their own declarations.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vectorstore.Store against a Weaviate class. Weaviate names properties per class, so the field mapping is fixed at construction and cannot vary per request.
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 class schema exists would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteIDs ¶
DeleteIDs removes objects by their Weaviate UUIDs. An empty slice is a no-op; unknown ids are ignored (idempotent).
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
type StoreConfig ¶
type StoreConfig struct {
// Client is the Weaviate client instance.
// Required: must be provided, otherwise initialization will fail.
Client *weaviate.Client
// ClassName is the name of the Weaviate class (collection) to use.
// Required: must be a non-empty string.
ClassName string
// InitializeSchema indicates whether to automatically create the class
// if it does not exist. When set to true, the class will be created
// with HNSW vector index configuration based on the chosen DistanceMetric.
// Optional: defaults to false.
InitializeSchema bool
// EmbeddingModel is the model used to generate vector embeddings from text.
// Required: must be provided for both embedding generation and schema initialization.
EmbeddingModel embedding.Model
// DocumentBatcher is responsible for batching documents before insertion.
// Required: must be provided to handle document batching logic.
DocumentBatcher vectorstore.Batcher
// DistanceMetric is the distance metric used for the HNSW vector index.
// Valid values: "cosine" (default), "dot", "l2-squared", "hamming", "manhattan".
// Optional: defaults to "cosine".
DistanceMetric DistanceMetric
// HybridAlpha controls the relative weight of vector evidence in native
// hybrid search. Nil preserves Weaviate's default; valid values are [0, 1].
HybridAlpha *float32
// MetadataProperties enumerates the metadata keys filters may select on.
// Each becomes a class property under InitializeSchema and is written
// alongside the document. A filter naming any other key is rejected,
// because a where filter on an undeclared property is not a narrower
// query — Weaviate has no such property to compare.
MetadataProperties []MetadataProperty
}
StoreConfig contains configuration options for Weaviate vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files