Skip to main content
Version: latest

agrag.vectordb.base.VectorStore

Bases: ABC

An external index whose hits must be joined to visible graph nodes.

Writes are idempotent and immediately visible on the same client. Reads and deletes of missing collections return empty results. Dense scores use (1 + cosine) / 2 or 1 / (1 + squared_distance). Hybrid scores are rank-only, with alpha one selecting dense order and zero lexical order. Lexical-only search omits records that do not match the query text. Labels filter by any overlap. Search limits above max_results are rejected.

Functions:

  • close – Release the client's connections.
  • collection_info – Return collection metadata, or None if it does not exist.
  • collection_name – Return the prefixed collection name for a kind.
  • delete – Delete ids, ignoring ids and collections that do not exist.
  • delete_collection – Delete the collection, doing nothing when it does not exist.
  • ensure_collection – Create a collection or reject dimension or distance mismatches.
  • hybrid_search – Return dense and lexical hits fused by alpha, in descending rank.
  • initialize – Connect and authenticate, raising VectorStoreError on failure.
  • list_ids – Return ids in ascending order, strictly after the exclusive cursor.
  • search – Return at most limit dense hits, best first, with graph-native scores.
  • upsert – Overwrite records by id; raise VectorStoreError if collection is absent.

Attributes:

close​

close() -> None

Release the client's connections.

collection_info​

collection_info(kind:VectorKind, *, exact_count:bool = True) -> CollectionInfo | None

Return collection metadata, or None if it does not exist.

Callers that need only dimensions or existence pass exact_count=False so the store can skip a full count and report its cheaper estimate.

collection_name​

collection_name(kind:VectorKind) -> str

Return the prefixed collection name for a kind.

collection_prefix​

collection_prefix: str

delete​

delete(kind:VectorKind, ids:Sequence[UUID]) -> None

Delete ids, ignoring ids and collections that do not exist.

delete_collection​

delete_collection(kind:VectorKind) -> None

Delete the collection, doing nothing when it does not exist.

ensure_collection​

ensure_collection(kind:VectorKind, *, dimensions:int, distance:Distance) -> None

Create a collection or reject dimension or distance mismatches.

DOT distance is unsupported and raises ValueError.

hybrid_search(kind:VectorKind, vector:Sequence[float], text:str, *, limit:int, alpha:float, labels:Sequence[str] | None = None) -> list[VectorHit]

Return dense and lexical hits fused by alpha, in descending rank.

initialize​

initialize() -> None

Connect and authenticate, raising VectorStoreError on failure.

list_ids​

list_ids(kind:VectorKind, *, after:UUID | None = None, limit:int = 1000) -> list[UUID]

Return ids in ascending order, strictly after the exclusive cursor.

A limit of zero returns no ids and a negative limit raises ValueError. Limits above max_results are allowed.

max_results​

max_results: int

name​

name: str
search(kind:VectorKind, vector:Sequence[float], *, limit:int, labels:Sequence[str] | None = None) -> list[VectorHit]

Return at most limit dense hits, best first, with graph-native scores.

upsert​

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

Overwrite records by id; raise VectorStoreError if collection is absent.