Skip to main content
Version: 0.0.4

agrag.vectordb.weaviate.WeaviateVectorStore

WeaviateVectorStore(*, settings:WeaviateSettings | None = None, client:Any | None = None, tracer:Tracer | None = None) -> None

Bases: VectorStore

A VectorStore backed by Weaviate, including native hybrid search.

The client connects lazily on first use, so constructing the store does not open a network connection. Weaviate does its own server-side BM25, so hybrid search needs no client-side sparse embedder.

Functions:

  • close – Release the backend connection.
  • collection_exists – Report whether a collection exists.
  • count – Count records in a collection.
  • delete – Delete records by id.
  • delete_collection – Delete a collection and all its objects.
  • ensure_collection – Create the collection if it does not exist.
  • hybrid_search – Search by dense vector and keyword text in one fused call.
  • initialize – Open the connection and check authentication.
  • retrieve – Fetch records by id.
  • scroll – Iterate records in a collection, in batches.
  • search – Search by dense vector only.
  • upsert – Write or overwrite records in a collection.

Parameters:

  • settings (WeaviateSettings | None) – Weaviate connection settings. Defaults to WeaviateSettings().
  • client (Any | None) – A pre-built Weaviate async client, for tests. When set, __init__ imports nothing and the store calls this object directly instead of building one.
  • tracer (Tracer | None) – Opens this store's spans.

close​

close() -> None

Release the backend connection.

collection_exists​

collection_exists(name:str) -> bool

Report whether a collection exists.

Parameters:

  • name (str) – The collection name.

Returns:

  • bool – True if the collection exists.

count​

count(collection:str, *, filters:dict[str, Any] | None = None) -> int

Count records in a collection.

Parameters:

  • collection (str) – The collection to count.
  • filters (dict[str, Any] | None) – A flat-dict filter on payload fields.

Returns:

  • int – The number of matching records.

delete​

delete(collection:str, ids:Sequence[UUID]) -> None

Delete records by id.

Parameters:

  • collection (str) – The collection to delete from.
  • ids (Sequence[UUID]) – The ids to delete.

delete_collection​

delete_collection(name:str) -> None

Delete a collection and all its objects.

Parameters:

  • name (str) – The collection name.

ensure_collection​

ensure_collection(name:str, *, dimensions:int, distance:Distance, hybrid:bool = False) -> None

Create the collection if it does not exist.

Parameters:

  • name (str) – The collection name.
  • dimensions (int) – The embedding dimension.
  • distance (Distance) – The distance metric new collections use.
  • hybrid (bool) – No-op for Weaviate, which needs no sparse provisioning.

Raises:

  • CollectionDimensionMismatchError – An existing object in the collection carries a vector of a different dimension. Weaviate keeps no schema-level dimension for self-provided vectors, so an existing collection with no vector-bearing object cannot be checked this way.
hybrid_search(collection:str, query_vector:Sequence[float], query_text:str, *, limit:int = 10, filters:dict[str, Any] | None = None, alpha:float = 0.5) -> list[VectorHit]

Search by dense vector and keyword text in one fused call.

Parameters:

  • collection (str) – The collection to search.
  • query_vector (Sequence[float]) – The dense query embedding.
  • query_text (str) – The query text, matched by keyword/BM25.
  • limit (int) – The maximum number of hits to return.
  • filters (dict[str, Any] | None) – A flat-dict filter on payload fields.
  • alpha (float) – The dense/keyword balance. 1.0 is pure dense, 0.0 is pure keyword.

Returns:

  • list[VectorHit] – The fused hits, highest score first.

Raises:

  • ValueError – limit is not positive, or exceeds MAX_SEARCH_LIMIT, or alpha is outside [0.0, 1.0].

initialize​

initialize() -> None

Open the connection and check authentication.

retrieve​

retrieve(collection:str, ids:Sequence[UUID]) -> list[VectorRecord]

Fetch records by id.

Parameters:

  • collection (str) – The collection to read.
  • ids (Sequence[UUID]) – The ids to fetch.

Returns:

scroll​

scroll(collection:str, *, limit:int = 100, page_offset:str | None = None, filters:dict[str, Any] | None = None, with_vectors:bool = False) -> tuple[list[VectorRecord], str | None]

Iterate records in a collection, in batches.

Parameters:

  • collection (str) – The collection to read.
  • limit (int) – The maximum number of records per page.
  • page_offset (str | None) – The cursor id from a previous scroll call.
  • filters (dict[str, Any] | None) – A flat-dict filter on payload fields.
  • with_vectors (bool) – Whether to return each record's vector.

Returns:

  • list[VectorRecord] – The page of records and the next page cursor, or None at the
  • str | None – end.
search(collection:str, query_vector:Sequence[float], *, limit:int = 10, filters:dict[str, Any] | None = None) -> list[VectorHit]

Search by dense vector only.

Parameters:

  • collection (str) – The collection to search.
  • query_vector (Sequence[float]) – The dense query embedding.
  • limit (int) – The maximum number of hits to return.
  • filters (dict[str, Any] | None) – A flat-dict filter on payload fields.

Returns:

  • list[VectorHit] – The matched hits, highest score first.

Raises:

  • ValueError – limit is not positive, or exceeds MAX_SEARCH_LIMIT.

upsert​

upsert(collection:str, records:Sequence[VectorRecord], *, batch_size:int = 256) -> None

Write or overwrite records in a collection.

Uses Weaviate's batch import, which replaces an existing object sharing a written id instead of rejecting it, giving real insert-or-replace semantics and per-call batching in one request.

Parameters:

  • collection (str) – The collection to write to.
  • records (Sequence[VectorRecord]) – The records to upsert, in order.
  • batch_size (int) – The number of records per backend write call. Must be positive.

Raises:

  • ValueError – batch_size is not positive.
  • VectorStoreError – At least one record in a batch failed to write.