Multi-Vector Search

Zvec supports multi-vector queries, allowing you to combine different embeddings in a single search.

When querying multiple vector embeddings, Zvec retrieves top candidates from each vector space independently.
Since similarity scores from different vector spaces might not be directly comparable, a re-ranker is required to fuse and and re-rank the results into a unified, relevance-ordered list.

Prerequisites

This guide assumes:

You have opened a collection with multiple vector fields
You're familiar with the basic vector querying concepts. If not, please review the single-vector search guide

Performing Multi-Vector Search

To run a multi-vector search, pass a list of vector query specification to the query() method and specify a fusion strategy via the reranker parameter.

This example queries both dense_embedding and sparse_embedding and uses a WeightedReranker to combine their results:

Query with multiple vectors

import zvec

result = collection.query(  
    topk=5,  # Retrieve top 5 candidates from each individual vector embedding
    vectors=[  # List of vector queries — one for each embedding space to search
        zvec.VectorQuery(field_name="dense_embedding", vector=[0.1] * 768),           
        zvec.VectorQuery(field_name="sparse_embedding", vector={1: 0.1, 37: 0.43}),   
    ],
    reranker=zvec.WeightedReRanker(  
        topn=3,  # Return top 3 documents after re-ranking
        metric=zvec.MetricType.IP,  # Metric used to interpret raw scores
        weights={  # Assign higher importance (weight) to 'dense_embedding'
            "dense_embedding": 1.2,
            "sparse_embedding": 1.0,
        },
    ),
)
print(result)

In multi-vector search, topk takes on a different meaning compared to single-vector queries:

topk (in query()): Controls how many candidate documents are retrieved from each vector field before re-ranking. A larger topk gives the re-ranker more candidates to work with, potentially improving final quality but increasing computational cost.
topn (in ReRanker): Controls how many final documents are returned after score fusion and re-ranking. This is your final result set size.

Re-ranking Strategies

Zvec provides different re-ranking strategies to combine scores from multiple vector fields.

Re-ranker	`WeightedReRanker`	`RrfReRanker` (Reciprocal Rank Fusion)
Approach	Combines normalized similarity scores using custom weights	Fuses results based only on ranking positions — no scores needed The RRF score at rank r is: $\text{RRF}(r) = \frac{1}{k + r + 1}$
Best for	• Scores are reasonably comparable across vector fields • You know the relative importance of each embedding type	• Scores come from different metrics or scales • You prefer a simple, robust, tuning-free method
Parameters	• `weights`: Dictionary mapping vector names to their relative importance • `metric`: The similarity metric used for score normalization	`rank_constant` (k): Controls how quickly rank influence decreases. Higher values reduce the dominance of top-ranked results.

Multi-Vector Search

Prerequisites

Example Collection Setup

Performing Multi-Vector Search

Re-ranking Strategies

On this page