Query

Single Query

Retrieves the nearest neighbors for a given query vector.

def query(self,
          query_vectors: List[float] = None,
          query_contents: str = None,
          top_k: int = None,
          n_probes: int = None,
          filters: Dict[str, Any] = {},
          include: List[str] = [],
          greedy: bool = False)

Parameters

Parameter	Type	Default	Description
query_vectors	List[float]	-	A single query vector as a list of floats (for single query).
query_contents	str	None	(Optional) Text content to auto-embed as query vector (requires embedding_model set during index creation).
top_k	int	None	(Optional) Number of nearest neighbors to return. When None, defaults to 100.
n_probes	int	None	(Optional) Number of lists probed during the query; higher values may increase recall but can also reduce performance. When None or 0, automatically determines the optimal value.
filters	Dict[str, Any]	{}	(Optional) A dictionary of filters to apply to vector metadata, limiting search scope to these vectors.
include	List[str]	[]	(Optional) List of item fields to return. Can include distance and metadata. When empty, only IDs are returned.
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_contents parameter can be used instead of query_vectors.

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 (always included), and optionally distance and metadata based on include. When include is empty (the default), only id is returned.

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_vectors = [0.1, 0.2, 0.3]  # Single query vector of dimension 3

# Perform a single query with distances
results = index.query(
    query_vectors=query_vectors, 
    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_vectors=query_vectors, 
    top_k=10, 
    n_probes=5, 
    include=[]
)
# Example output:
# [{"id": "101"}, {"id": "102"}]

Single Query with Metadata:

results = index.query(
    query_vectors=query_vectors, 
    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 = None,
          n_probes: int = None,
          filters: Dict[str, Any] = {},
          include: List[str] = [],
          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	None	(Optional) Number of nearest neighbors to return. When None, defaults to 100.
n_probes	int	None	(Optional) Number of lists probed during the query; higher values may increase recall but can also reduce performance. When None or 0, automatically determines the optimal value.
filters	Dict[str, Any]	{}	(Optional) A dictionary of filters to apply to vector metadata, limiting search scope to these vectors.
include	List[str]	[]	(Optional) List of item fields to return. Can include distance and metadata. When empty, only IDs are returned.
greedy	bool	False	(Optional) Whether to use greedy search (higher recall with same n_probes).

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[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 (always included), and optionally distance and metadata based on include. When include is empty (the default), only id is returned.

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 with distances included
results = index.query(query_vectors=query_vectors, include=["distance"])
# 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}]
# ]

---

NumPy Query

A high-performance query variant that returns only integer IDs as a NumPy array. This is optimized for performance-critical workloads where metadata and distances are not needed.

def query_numpy(self,
                query_vectors: np.ndarray,
                top_k: int = 100,
                n_probes: int = 0,
                greedy: bool = False,
                batch: bool = False) -> np.ndarray

Parameters

Parameter	Type	Default	Description
query_vectors	np.ndarray	-	Query vectors as a NumPy array. For a single query, a 1D array; for batch queries, a 2D array.
top_k	int	100	(Optional) Number of nearest neighbors to return.
n_probes	int	0 (auto)	(Optional) Number of lists probed during the query. When set to 0, automatically determines the optimal value.
greedy	bool	False	(Optional) Whether to use greedy search (higher recall with same n_probes).
batch	bool	False	(Optional) Whether to treat the input as a batch of query vectors.

Returns

np.ndarray: A NumPy array of integer IDs for the nearest neighbors. For a single query, returns a 1D array of shape (top_k,). For batch queries, returns a 2D array of shape (num_queries, top_k).

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

import numpy as np

# Single query
query_vector = np.array([0.1, 0.2, 0.3], dtype=np.float32)
ids = index.query_numpy(query_vectors=query_vector, top_k=10)
# ids is a 1D np.ndarray of integer IDs, e.g. array([101, 102, 103, ...])

# Batch query
query_vectors = np.array([
    [0.1, 0.2, 0.3],
    [0.4, 0.5, 0.6]
], dtype=np.float32)
ids = index.query_numpy(query_vectors=query_vectors, top_k=5, batch=True)
# ids is a 2D np.ndarray of shape (2, 5)

query_numpy is a high-performance variant that returns only integer IDs. Use the standard query() method if you need distances, metadata, or string IDs.