Skip to main content

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.
  • commit_pending – Promote one job's staged records to committed records.
  • count – Count records in a collection.
  • delete – Delete records by id.
  • delete_collection – Delete a collection and all its points.
  • delete_pending – Delete one job's staged records, leaving committed records alone.
  • 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.

commit_pending​

commit_pending(collection:str, *, job_id:UUID) -> None

Promote one job's staged records to committed records.

Each staged record is written under its real id, which replaces any committed record with that id, and the staged copy is deleted. The method reads the first page of staged records again after each delete, so it needs no offset. Re-running after a failure finishes the remaining records.

Parameters:

  • collection (str) – The collection the job wrote to.
  • job_id (UUID) – The committed job whose records become visible.

Raises:

  • RuntimeError – A delete left the same staged records in place.

count​

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

Count records in a collection.

Counts committed records only, unless pending_job_id names a job.

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.
  • pending_job_id (UUID | None) – Count only that job's staged records instead of the committed ones.

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.

delete_pending​

delete_pending(collection:str, *, job_id:UUID) -> None

Delete one job's staged records, leaving committed records alone.

Parameters:

  • collection (str) – The collection the job wrote to.
  • job_id (UUID) – The rolled-back job whose records are deleted.

Raises:

  • RuntimeError – A delete left the same staged records in place.

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.

Searches committed records only; staged records stay hidden.

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, pending_job_id:UUID | None = None) -> tuple[list[VectorRecord], str | None]

Iterate records in a collection, in batches.

Reads committed records only, unless pending_job_id names a job. Do not write or delete records of the set being read between pages: a backend may page by position.

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.
  • pending_job_id (UUID | None) – Read only that job's staged records instead of the committed ones.

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.

Searches committed records only; staged records stay hidden.

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, pending_job_id:UUID | None = None) -> 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.
  • pending_job_id (UUID | None) – The in-flight Cutover Job writing these records. The store keeps them under staging ids, hidden from search, scroll and count until commit_pending promotes them, so a committed record with the same id stays searchable and survives delete_pending. None writes committed records.

Raises:

  • ValueError – batch_size is not positive, or a payload uses a key the store reserves for pending records (_pending, _pending_job_id, _target_id).