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, a Query is a query specification that describes the field and query source used for a search. Query APIs accept one or more Query specifications depending on whether you are performing a single- or multi-query search.
A single Query can target either vector search or full-text search, but not both at the same time.
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
- For vector search, provide an explicit
param(optional): Index-specific query parameters (e.g.,effor HNSW ordefault_operatorfor 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
Grouped Search
Group vector search results by a scalar field
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=3,
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(
weights=[1.2, 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,
)Grouped Search
import zvec
groups = collection.group_by_query(
query=zvec.Query(
field_name="dense_embedding",
vector=[0.1] * 768, # Replace with a real embedding in practice
),
group_by_field_name="publish_year", # Group by publication year
group_count=3, # Return up to 3 groups
topk_per_group=2, # Return up to 2 documents per group
)
for group in groups:
print(group.group_by_value, group.docs)