Skip to main content
Version: 0.0.4

agrag.vectordb.qdrant.QdrantVectorStore

QdrantVectorStore(*, settings:QdrantSettings | None = None, sparse_embedder:SparseEmbedder | None = None, client:Any | None = None, models:Any | None = None, tracer:Tracer | None = None) -> None

Bases: VectorStore

A VectorStore backed by Qdrant, including native hybrid search.

The client connects lazily on first use, so constructing the store does not open a network connection. Hybrid search builds its sparse query with a SparseEmbedder that defaults to FastEmbed BM25 and loads only when a hybrid call first runs, not at construction.

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, fused by a weighted blend.
  • initialize – Check connectivity and authentication.
  • invalidate_collection – Drop cached hybrid-state and distance-metric knowledge of a collection.
  • 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 (QdrantSettings | None) – Qdrant connection settings. Defaults to QdrantSettings().
  • sparse_embedder (SparseEmbedder | None) – The sparse embedder hybrid search uses. Defaults to a lazily-built FastEmbedBM25Embedder.
  • client (Any | None) – A pre-built AsyncQdrantClient, for tests. When set, __init__ imports nothing and the store calls this object directly instead of building one.
  • models (Any | None) – The qdrant_client.models module, for tests. Pair with client so filter/payload helpers work without needing the real qdrant_client package installed at all.
  • 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 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.
  • distance (Distance) – The distance metric new collections use.
  • hybrid (bool) – Whether to provision the named sparse vector hybrid search needs.

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, fused by a weighted blend.

Qdrant's native fusion methods (RRF, DBSF) have no continuous dense/keyword weight, so this runs the dense and sparse (BM25) searches independently, min-max normalizes each result set's scores to [0, 1], then combines them per id as alpha * dense + (1 - alpha) * sparse. Each side fetches a wider candidate pool than limit so a document strong on only one signal still has a chance to reach the blended top results.

Parameters:

  • collection (str) – The collection to search.
  • query_vector (Sequence[float]) – The dense query embedding.
  • query_text (str) – The query text, matched by 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 blended hits, highest combined score first.

Raises:

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

initialize​

initialize() -> None

Check connectivity and authentication.

invalidate_collection​

invalidate_collection(name:str) -> None

Drop cached hybrid-state and distance-metric knowledge of a collection.

This store caches a collection's hybrid support and distance metric after the first call that resolves them, on the assumption that it alone (via ensure_collection/delete_collection) owns the collection's lifecycle for as long as this instance is in use. If something outside this instance deletes and recreates a collection under the same name with different config, call this first so the next call re-resolves that collection's state from the backend instead of trusting the stale cache.

Parameters:

  • name (str) – The collection name.

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

When collection has sparse-vector support (created or previously seen with ensure_collection(..., hybrid=True)), each record's payload["text"] is also sparse-embedded and stored under the named sparse vector, so hybrid_search's keyword arm has real vectors to match. A record with no text payload key gets an empty sparse vector and only ever surfaces through the dense side of a hybrid search.

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.