soev_retrieval.adapters.weaviate
A VectorStore over a stock Weaviate client: a collection, or a tenant of one, per target.
Install the soev-retrieval[weaviate] extra to use this package.
Store
The store maps each target to a collection, or to a tenant of a collection, and searches it.
WeaviateVectorStore
dataclassWeaviateVectorStore(client, *, resolve=…, document_property='document_id', id_of=…, alpha=0.7, fields_of=None, extra_filter=None, bm25_properties=None, fusion=None)A VectorStore over one Weaviate cluster.
Connecting and closing the client stay with whoever built it.
Configure the store with arguments, and do not subclass it. Each argument after client is
keyword-only.
An operator the field spec admits but this store does not compile is refused as InvalidQueryError.
hybrid with vector=None relies on the collection's vectorizer, and a collection without one answers
StoreUnavailable, as Weaviate reports it. near_vector scores by one minus the distance.
Each method raises StoreUnavailable when Weaviate cannot be reached, times out or fails the query, and
InvalidQueryError when Weaviate refuses the input of the call.
Example
import weaviate
from soev_retrieval.adapters.weaviate import WeaviateVectorStore, tenants_in
async with weaviate.use_async_with_local() as client:
store = WeaviateVectorStore(client, resolve=tenants_in("Documents"))
hits = await store.hybrid("tenant-a", query="parking permit", limit=5)paramclientWeaviateAsyncClientThe Weaviate async client that the store calls.
paramresolveCallable[[Target], tuple[str, str | None]]= …A function that maps a target to (collection, tenant). tenant is None without
multi-tenancy. It can raise InvalidQueryError for a target it will not serve. It is synchronous, like
extra_filter. So build any data that they read before you build the store. The default makes the
target the collection name, with no tenant.
paramdocument_propertystr= 'document_id'The stored field naming a chunk's document. A hit without it raises Unconfigured.
paramid_ofCallable[[Any], str]= …Derive the chunk id from a Weaviate object. The default is the object's uuid as text.
paramalphafloat= 0.7The hybrid blend when a call passes alpha=None. 1.0 is pure vector, 0.0 pure keyword.
paramfields_ofMapping[str, FieldSpec] | None= NoneThe field spec per target. Without it, the schema is read once per target and kept for the
instance's lifetime, so give it for a store built per request. Returned properties are only the
spec's fields. A target that fields_of does not hold is refused as InvalidQueryError.
paramextra_filterExtraFilter | None= NoneA function that returns the Weaviate filter for a target, or None. The store adds the
filter with AND to each search and each fetch. Use it for a condition that the caller does not send in
where.
parambm25_propertiesSequence[str] | None= NoneWhat the keyword side of hybrid and bm25 searches. None for all.
paramfusionHybridFusion | None= NoneThe fusion method of hybrid. None uses the default of Weaviate.
methodhybridasync (target, *, query, vector=None, limit, where=None, alpha=None) -> Sequence[Hit]Search target with the hybrid search of Weaviate: a vector match blended with a keyword match.
paramtargetTargetThe target to search. resolve maps it to a collection and a tenant.
paramquerystrThe text of the keyword side. The keyword side searches bm25_properties.
paramvectorSequence[float] | None= NoneThe query embedding. None lets the vectorizer of the collection embed query.
paramlimitintThe maximum number of hits.
paramwhereExpression | None= NoneThe filter on the candidates, or None for no filter.
paramalphafloat | None= NoneThe weight of the vector side: 1.0 is pure vector, 0.0 pure keyword. None uses the alpha of
the store.
Returns
Sequence[Hit]At most limit hits, best first, with the fusion score of Weaviate. The list is empty without a call to
Weaviate when where matches nothing.
Raises:
InvalidQueryError: The target is unknown, orwherenames a field, an operator or an operand that the store does not serve.StoreUnavailable: Weaviate gave no answer, or the collection has no vectorizer forvector=None.Unconfigured: A hit has nodocument_property.
methodnear_vectorasync (target, *, vector, limit, where=None) -> Sequence[Hit]Search target by similarity to vector alone.
paramtargetTargetThe target to search. resolve maps it to a collection and a tenant.
paramvectorSequence[float]The query embedding.
paramlimitintThe maximum number of hits.
paramwhereExpression | None= NoneThe filter on the candidates, or None for no filter.
Returns
Sequence[Hit]At most limit hits, best first. The score is one minus the distance that Weaviate returns. The list is
empty without a call to Weaviate when where matches nothing.
Raises:
InvalidQueryError: The target is unknown, orwherenames a field, an operator or an operand that the store does not serve.StoreUnavailable: Weaviate gave no answer.Unconfigured: A hit has nodocument_property.
methodbm25async (target, *, query, limit, where=None) -> Sequence[Hit]Search target by keyword match on query alone, with the BM25 search of Weaviate.
paramtargetTargetThe target to search. resolve maps it to a collection and a tenant.
paramquerystrThe keyword query. The search covers bm25_properties.
paramlimitintThe maximum number of hits.
paramwhereExpression | None= NoneThe filter on the candidates, or None for no filter.
Returns
Sequence[Hit]At most limit hits, best first, with the BM25 score of Weaviate. A chunk that matches no term is not
returned. The list is empty without a call to Weaviate when where matches nothing.
Raises:
InvalidQueryError: The target is unknown, orwherenames a field, an operator or an operand that the store does not serve.StoreUnavailable: Weaviate gave no answer.Unconfigured: A hit has nodocument_property.
methodfetchasync (target, *, where=None, limit, order_by=None, descending=False) -> Sequence[Chunk]Return the chunks of target that match where, with nothing searched for.
paramtargetTargetThe target to read. resolve maps it to a collection and a tenant.
paramwhereExpression | None= NoneThe filter on the chunks, or None for no filter.
paramlimitintThe maximum number of chunks.
paramorder_bystr | None= NoneThe field to sort on, ascending unless descending. None keeps the order of Weaviate.
paramdescendingbool= FalseIf true, sort on order_by from high to low.
Returns
Sequence[Chunk]At most limit chunks. The list is empty without a call to Weaviate when where matches nothing.
Raises:
InvalidQueryError: The target is unknown,order_byis not a field of the target, orwherenames a field, an operator or an operand that the store does not serve.StoreUnavailable: Weaviate gave no answer.Unconfigured: A chunk has nodocument_property.
methodfieldsasync (target) -> FieldSpecReturn the stored fields of target and which of them a filter can name.
With fields_of, the spec is its entry for target. Without it, the store reads the schema of the
collection once and keeps the spec for the lifetime of the instance. A text property with field
tokenization becomes a keyword field, and a property of an unknown data type is left out. A property is
filterable when its index is filterable.
paramtargetTargetThe target to describe. resolve maps it to a collection and a tenant.
Returns
FieldSpecThe field spec of target.
Raises:
InvalidQueryError:fields_ofhas no entry fortarget, or Weaviate has no such collection.StoreUnavailable: Weaviate gave no answer.
tenants_in
functiontenants_in(collection) -> Callable[[Target], tuple[str, str | None]]Return the resolution for a multi-tenant layout: every target is a tenant of collection.
Pass the result as resolve of a WeaviateVectorStore.
paramcollectionstrThe name of the one collection that holds every target as a tenant.
Returns
Callable[[Target], tuple[str, str | None]]A function that maps a target to (collection, target).
ExtraFilter
type aliasExtraFilter = …A function that returns the Weaviate filter to add to each query on a target.
The store calls it with the target of each search and each fetch, and adds the returned filter with AND to the
filter of the call. It returns a built Weaviate filter, for example Filter.by_property("tenant").equal("a") of
weaviate.classes.query, or None to add nothing. The store never takes the returned filter apart.