Search Documents
The query() method supports vector similarity search, conditional filtering (like a SQL WHERE clause), or both combined in a hybrid query.
It returns a list of Doc objects, each containing the matched document and its relevance score.
Query
In Zvec, all queries are performed by passing parameters through a Query object to the query() method.
Each VectorQuery specifies:
field_name: The name of the vector field to search- Query source (exactly one required):
- An explicit
vector, or - a document
id(to reuse the stored embedding of an existing document)
You must provide exactly one of
vectororid. Specifying both will raise an error. - An explicit
param(optional): Index-specific query parameters (e.g.,effor HNSW)
Each ZVecQuery specifies:
fieldName: The name of the vector field to searchvector: The query vectorparams(optional): Index-specific query parameters (e.g.,effor HNSW)
Query Types
Single-Vector Search
Find documents using a single vector embedding
Multi-Vector Search
Combine multiple embeddings with re-ranking
Conditional Filtering
Filter documents using scalar field conditions
Filtered Vector Search
Combine vector search with conditional filters
Quick Start Examples
Single-Vector Search
import zvec
result = collection.query(
vectors=zvec.VectorQuery(
field_name="dense_embedding",
vector=[0.1] * 768, # Use real embedding in practice
),
topk=10,
)Multi-Vector Search
import zvec
result = collection.query(
topk=10,
vectors=[
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,
metric=zvec.MetricType.IP,
weights={
"dense_embedding": 1.2,
"sparse_embedding": 1.0,
},
),
)
print(result)Conditional Filtering
result = collection.query(filter="publish_year < 1999", topk=50)Hybrid Search
import zvec
result = collection.query(
vectors=zvec.VectorQuery(
field_name="dense_embedding",
vector=[0.1] * 768, # Use real embedding in practice
),
filter="publish_year < 1999",
topk=10,
)