Query

Single Query

Retrieves the nearest neighbors for a given query vector.

def query(self,
          query_vector: List[float],
          top_k: int = 100,
          n_probes: int = 1,
          greedy: bool = False,
          return_distances: bool = True)

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.
greedy	bool	False	(Optional) Whether to use greedy search (higher recall with same n_probes).
return_distances	bool	True	(Optional) If True, each result includes distance.

Returns

List[Dict[str, Union[int, float, Dict[]]]]: List of results for the query vector. Each dictionary contains id and optionally distance if return_distances is True.

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, return_distances=True)
# 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, return_distances=False)
# Example output:
# [{"id": 101}, {"id": 102}]

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,
          greedy: bool = False,
          return_distances: bool = True)

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.
greedy	bool	False	(Optional) Whether to use greedy search (higher recall with same n_probes).
return_distances	bool	True	(Optional) If True, each result includes (ID, distance). If False, only IDs are returned.

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 and optionally distance if return_distances is True.

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)
# Output example:
# [
#     [{"id": 101, "distance": 0.05}, {"id": 102, "distance": 0.1}],
#     [{"id": 201, "distance": 0.2}, {"id": 202, "distance": 0.3}]
# ]