Skip to main content

agrag.retrieval.methods.vector.vector_search

vector_search(query:str, *, embedder:Embedder, graph_store:GraphStore, vector_store:VectorStore | None, collection:str, labels:Sequence[str], limit:int, filters:SearchFilters | None, settings:RetrievalSettings, query_vector:Sequence[float] | None = None, tracer:Tracer | None = None) -> list[VectorHit]

Embed query and search on whichever store is configured.

When vector_store is set, runs hybrid_search there (dense plus BM25, blended by settings.hybrid_alpha) against collection. When it is None, runs GraphStore's native vector_search once per label in labels and merges the hits, ignoring hybrid_alpha since that path is dense-only. One native vector index exists per label, so a search over several labels is several searches.

Both paths exclude records an in-flight Cutover Job wrote: the VectorStore path with a committed-only payload filter, the native path inside the vector query itself. A caller can therefore never receive an uncommitted job's node or vector.

Parameters:

  • query (str) – The natural-language query text to embed.
  • embedder (Embedder) – Produces the query's dense vector.
  • graph_store (GraphStore) – The GraphStore-native fallback target.
  • vector_store (VectorStore | None) – The optional VectorStore target. None selects the GraphStore-native path.
  • collection (str) – The VectorStore collection name.
  • labels (Sequence[str]) – The node labels to search on the GraphStore-native path, each backed by its own vector index.
  • limit (int) – Maximum hits to return.
  • filters (SearchFilters | None) – Constraints translated to whichever store is searched. Labels are a payload key on the VectorStore path and choose the searched indexes on the native path, so they are not sent as node property filters.
  • settings (RetrievalSettings) – Supplies hybrid_alpha for the VectorStore path.
  • query_vector (Sequence[float] | None) – Precomputed query embedding. None embeds query.
  • tracer (Tracer | None) – Opens the search span. None opens no recorded span.

Returns:

  • list[VectorHit] – Ranked VectorHits, from whichever store was searched.

Raises:

  • ValueError – The native path was selected with no labels to search.