Skip to main content
Version: 0.0.4

agrag.vectordb.base.VectorStore

Bases: ABC

A vector database backend: collection lifecycle, writes, and search.

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 points.
  • ensure_collection – Create the collection if it does not exist.
  • hybrid_search – Search by dense vector and keyword text in one fused call.
  • initialize – Check connectivity and 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.

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: a scalar value means exact match, a list value means any of, and all keys are AND-ed together. Keys must be valid identifiers (letters, digits, underscore, not starting with a digit) to stay portable: Milvus compiles them into a filter expression and Neo4j's GraphStore counterpart compiles them into Cypher, so both reject other characters, while Qdrant and Weaviate accept arbitrary payload keys.

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 points.

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. If the collection already exists with a different dimension, this raises.
  • distance (Distance) – The distance metric new collections use.
  • hybrid (bool) – Whether to additionally provision the sparse-vector configuration hybrid search needs. Ignored by backends that need no such provisioning.

Raises:

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. Must have been created with ensure_collection(..., hybrid=True).
  • 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: a scalar value means exact match, a list value means any of, and all keys are AND-ed together. Keys must be valid identifiers (letters, digits, underscore, not starting with a digit) to stay portable: Milvus compiles them into a filter expression and Neo4j's GraphStore counterpart compiles them into Cypher, so both reject other characters, while Qdrant and Weaviate accept arbitrary payload keys.
  • alpha (float) – The dense/keyword balance. 1.0 is pure dense, 0.0 is pure keyword. Weaviate and Milvus apply this weight natively. Qdrant's native fusion (Reciprocal Rank Fusion) has no continuous weight, so it applies alpha by blending two independently-scored, min-max normalized result sets instead of a single native fused call.

Returns:

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

Raises:

  • ValueError – limit is not positive, or exceeds agrag.common.validation.MAX_SEARCH_LIMIT, or alpha is outside [0.0, 1.0]. Enforced uniformly across backends since they otherwise fail differently outside that range.

initialize​

initialize() -> None

Check connectivity and authentication.

Raises:

  • VectorStoreError – The backend is unreachable, or the credentials are rejected.

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 offset from a previous scroll call, or None to start at the beginning.
  • filters (dict[str, Any] | None) – A flat-dict filter: a scalar value means exact match, a list value means any of, and all keys are AND-ed together. Keys must be valid identifiers (letters, digits, underscore, not starting with a digit) to stay portable: Milvus compiles them into a filter expression and Neo4j's GraphStore counterpart compiles them into Cypher, so both reject other characters, while Qdrant and Weaviate accept arbitrary payload keys.
  • with_vectors (bool) – Whether to return each record's vector.

Returns:

  • list[VectorRecord] – The page of records and the next page offset, 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: a scalar value means exact match, a list value means any of, and all keys are AND-ed together. Keys must be valid identifiers (letters, digits, underscore, not starting with a digit) to stay portable: Milvus compiles them into a filter expression and Neo4j's GraphStore counterpart compiles them into Cypher, so both reject other characters, while Qdrant and Weaviate accept arbitrary payload keys.

Returns:

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

Raises:

  • ValueError – limit is not positive, or exceeds agrag.common.validation.MAX_SEARCH_LIMIT. Enforced uniformly across backends since they otherwise fail differently outside that range.

upsert​

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

Write or overwrite records in a collection.

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.