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.
Performing Single-Vector Search
To perform a single-vector similarity search, use the query() method and provide a single vector query specification.
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 map from vector field names to their corresponding embedding values.
This is only populated ifinclude_vector=Trueis passed in the query.fields: A map from scalar field names to their stored values.
By default, all scalar fields are returned; this can be restricted using theoutput_fieldsparameter.
Parameters
When performing a vector search, the query() method accepts two kinds of parameters:
- common parameters, which apply universally regardless of the underlying index type
- index-specific parameters, which allow fine-tuning of search behavior based on the vector index in use
Common Parameters
| Parameter | Description |
|---|---|
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 option in the Query object.
The exact type and structure of these param depend on the vector index used for the target vector embedding. 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.