Query

Single Query

Retrieves the nearest neighbors for a given query vector.

def query(self,
          query_vector: List[float] = None,
          query_contents: Union[str, Image] = None,
          top_k: int = 100,
          n_probes: int = 1,
          filters: Dict[str, Any] = None,
          include: List[str] = ["distance"],
          greedy: bool = False)

Parameters

Parameter	Type	Default	Description
`query_vector`	`List[float]`	-	A single query vector as a list of floats (for single query).
`top_k`	`int`	`100`	(Optional) Number of nearest neighbors to return.
`n_probes`	`int`	`1`	(Optional) Number of lists probed during the query; higher values may increase recall but can also reduce performance.
`filters`	`Dict[str, Any]`	`None`	(Optional) A dictionary of filters to apply to vector metadata, limiting search scope to these vectors.
`include`	`List[str]`	`"distance"`	(Optional) List of item fields to return. Can include `distance`, `metadata`, and `vector` (`vector` only for `IVFFlat` indexes).
`greedy`	`bool`	`False`	(Optional) Whether to use greedy search (higher recall with same `n_probes`).

If embedding auto-generation is enabled (by setting the embedding_model parameter in create_index(), then the query_string can be used instead of query_vector.

filters use a subset of the MongoDB Query and Projection Operators. For instance: filters: { "$and": [ { "label": "cat" }, { "confidence": { "$gte": 0.9 } } ] } means that only vectors where label == "cat" and confidence >= 0.9 will be considered for encrypted vector search. For more info on metadata, see Metadata Filtering.

Returns

List[Dict[str, Union[int, float, Dict[]]]]: List of results for the query vector. Each result is a list of top_k dictionaries, each containing id, as well as distance, metadata, and vector based on include.

Exceptions

ValueError

Throws if the query vector has incompatible dimensions with the index.
Throws if the index was not created or loaded yet.

RuntimeError

Throws if the query could not be executed.

Example Usage

Single Query with Distances:

# Load index
index = client.load_index(index_name=index_name, index_key=index_key)

# Define a single query vector
query_vector = [0.1, 0.2, 0.3]  # Single query vector of dimension 3

# Perform a single query with distances
results = index.query(query_vector=query_vector, top_k=2, n_probes=5, include=["distance"])
# Example output:
# [{"id": "101", "distance": 0.05}, {"id": "102", "distance": 0.1}]

Single Query without Distances:

results = index.query(query_vector=query_vector, top_k=10, n_probes=5, include=[])
# Example output:
# [{"id": "101"}, {"id": "102"}]

Single Query with Metadata:

results = index.query(query_vector=query_vector, top_k=10, n_probes=5, filters={"label": "dog"}, include=["metadata"])
# Example output:
# [{"id": "101", "metadata": {"label": "dog", "temperament": "good boy"}},
#  {"id": "102", "metadata": {"label": "dog", "temperament": "hyper"})]]

Batched Queries

Retrieves the nearest neighbors for one or more query vectors.

def query(self,
          query_vectors: Union[np.ndarray, List[List[float]]],
          top_k: int = 100,
          n_probes: int = 1,
          filters: Dict[str, Any] = None,
          include: List[str] = ["distance"],
          greedy: bool = False)

Parameters

Parameter	Type	Default	Description
`query_vectors`	`np.ndarray` or `List[List[float]]`	-	A 2D NumPy array or list of lists, where each inner list represents a query vector (for batch query).
`top_k`	`int`	`100`	(Optional) Number of nearest neighbors to return.
`n_probes`	`int`	`1`	(Optional) Number of lists probed during the query; higher values may increase recall but can also reduce performance.
`filters`	`Dict[str, Any]`	`None`	(Optional) A dictionary of filters to apply to vector metadata, limiting search scope to these vectors.
`include`	`List[str]`	`"distance"`	(Optional) List of item fields to return. Can include `distance`, `metadata`, and `vector` (`vector` only for `IVFFlat` indexes).
`greedy`	`bool`	`False`	(Optional) Whether to use greedy search (higher recall with same `n_probes`).

Returns

List[List[Dict[str, Union[int, float, Dict[]]]]]: List of results for each query vector. Each result is a list of top_k dictionaries, each containing id, as well as distance, metadata, and vector based on include.

Exceptions

ValueError

Throws if the query vectors have incompatible dimensions with the index.
Throws if the index was not created or loaded yet.

RuntimeError

Throws if the query could not be executed.

Example Usage

Batch Query with Distances:

import numpy as np

# Multiple query vectors
query_vectors = np.array([
    [0.1, 0.2, 0.3],
    [0.4, 0.5, 0.6]
])

# Query using default parameters and distances
results = index.query(query_vectors=query_vectors)
# Example output:
# [
#     [{"id": "item_101", "distance": 0.05}, {"id": "item_202", "distance": 0.1}],
#     [{"id": "item_202", "distance": 0.2}, {"id": "item_303", "distance": 0.3}]
# ]

Introduction

Client

Encrypted Index

Types & Getters

Single Query

Parameters

Returns

Exceptions

Example Usage

Batched Queries

Parameters

Returns

Exceptions

Example Usage

​Single Query

​Parameters

​Returns

​Exceptions

​Example Usage

​Batched Queries

​Parameters

​Returns

​Exceptions

​Example Usage

Single Query

Parameters

Returns

Exceptions

Example Usage

Batched Queries

Parameters

Returns

Exceptions

Example Usage