Single-Vector Search
Single-vector search finds documents most similar to a single query embedding. This is the most common search pattern in vector databases.
Prerequisites
This guide assumes you have opened a collection and have a collection object ready.
VectorQuery
In Zvec, all vector similarity searches are performed by passing one or more VectorQuery objects 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).
Performing Single-Vector Search
To perform a single-vector similarity search, call the query() method with a single VectorQuery object.
All queries return a list[Doc] containing the top-k most similar documents, sorted by relevance score.
Each Doc object includes:
id: The document identifier.score: The similarity score.vectors: A dictionary of vector embeddings.
This is only populated ifinclude_vector=Trueis passed in the query.fields: A dictionary of scalar field values.
By default, all scalar fields are returned; this can be restricted using theoutput_fieldsparameter.
Common Parameters
| Parameter | Description |
|---|---|
vectors | The VectorQuery object specifying the query vector and target field. |
topk | The number of most similar documents to return. |
include_vector | If True, the returned Doc objects include the full vector embeddings (disabled by default for performance). |
output_fields | An optional list of scalar field names to include in results. If omitted, all scalar fields are returned. |
filter | An optional SQL-like boolean expression to restrict results. See filtered search for details. |
The reranker parameter is part of the query() interface but only applies to multi-vector search.
Do not provide it in single-vector queries.
Index-Specific Parameters
You can fine-tune search behavior by passing index-specific query parameters through the param in VectorQuery.
The param option accepts different parameter classes depending on the index type of your vectors — for example,
VectorQuery(..., param=HnswQueryParam())for HNSW indexes,VectorQuery(..., param=IVFQueryParam())for IVF-based indexes.
The available query options are determined by this index type. If omitted, default values are used.
Each index type exposes its own set of tunable options at query time. For full details:
Mismatched parameter classes will cause an error. For instance, using IVFQueryParam with an HNSW-indexed vector (or vice versa) is not allowed.