Search Documents
The query() method supports vector similarity search, full-text search (BM25 ranking), conditional filtering (like a SQL WHERE clause), or combinations of these.
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 Query specifies:
field_name: The name of the vector or full-text field to search- Query source:
- For vector search, provide an explicit
vectoror a documentid(to reuse the stored embedding of an existing document) - For full-text search, provide an
ftsclause
A single
Querycan target either vector search or full-text search, but not both at the same time. - For vector search, provide an explicit
param(optional): Index-specific query parameters (e.g.,effor HNSW ordefault_operatorfor full-text search)
Each ZVecQuery specifies:
fieldName: The name of the vector or full-text field to search- Query source:
- For vector search, provide
vector - For full-text search, provide
fts
- For vector search, provide
params(optional): Index-specific query parameters (e.g.,effor HNSW ordefaultOperatorfor full-text search)
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
Full-Text Search
Search documents by text content with BM25 ranking
Quick Start Examples
Single-Vector Search
import zvec
result = collection.query(
queries=zvec.Query(
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,
queries=[
zvec.Query(field_name="dense_embedding", vector=[0.1] * 768),
zvec.Query(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(
queries=zvec.Query(
field_name="dense_embedding",
vector=[0.1] * 768, # Use real embedding in practice
),
filter="publish_year < 1999",
topk=10,
)Full-Text Search
from zvec.model.param.query import Fts, Query
result = collection.query(
queries=Query(
field_name="content",
fts=Fts(match_string="machine learning"),
),
topk=10,
)