Skip to main content

​
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

ParameterTypeDefaultDescription
query_vectorList[float]-A single query vector as a list of floats (for single query).
top_kint100(Optional) Number of nearest neighbors to return.
n_probesint1(Optional) Number of lists probed during the query; higher values may increase recall but can also reduce performance.
filtersDict[str, Any]None(Optional) A dictionary of filters to apply to vector metadata, limiting search scope to these vectors.
includeList[str]"distance"(Optional) List of item fields to return. Can include distance, metadata, and vector (vector only for IVFFlat indexes).
greedyboolFalse(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

  • Throws if the query vector has incompatible dimensions with the index.
  • Throws if the index was not created or loaded yet.
  • 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

ParameterTypeDefaultDescription
query_vectorsnp.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_kint100(Optional) Number of nearest neighbors to return.
n_probesint1(Optional) Number of lists probed during the query; higher values may increase recall but can also reduce performance.
filtersDict[str, Any]None(Optional) A dictionary of filters to apply to vector metadata, limiting search scope to these vectors.
includeList[str]"distance"(Optional) List of item fields to return. Can include distance, metadata, and vector (vector only for IVFFlat indexes).
greedyboolFalse(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, as well as distance, metadata, and vector based on include.

​
Exceptions

  • Throws if the query vectors have incompatible dimensions with the index.
  • Throws if the index was not created or loaded yet.
  • 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}]
# ]
⌘I