> ## Documentation Index
> Fetch the complete documentation index at: https://cyborg-encryption-copy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Query

## Single Query

Retrieves the nearest neighbors for a given query vector.

```python theme={null}
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

<AccordionGroup>
  <Accordion title="ValueError">
    * Throws if the query vector has incompatible dimensions with the index.
    * Throws if the index was not created or loaded yet.
  </Accordion>

  <Accordion title="RuntimeError">
    * Throws if the query could not be executed.
  </Accordion>
</AccordionGroup>

### Example Usage

*Single Query with Distances*:

```python theme={null}
# 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*:

```python theme={null}
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.

```python theme={null}
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

<AccordionGroup>
  <Accordion title="ValueError">
    * Throws if the query vectors have incompatible dimensions with the index.
    * Throws if the index was not created or loaded yet.
  </Accordion>

  <Accordion title="RuntimeError">
    * Throws if the query could not be executed.
  </Accordion>
</AccordionGroup>

### Example Usage

*Batch Query with Distances*:

```python theme={null}
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}]
# ]
```