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

# Query (Binary)

`query_binary` is the high-throughput query path. Query vectors are sent as base64-encoded binary instead of JSON arrays, which is significantly faster for large batch queries.

```python theme={null}
results = index.query_binary(
    query_vectors,
    top_k=None,
    n_probes=None,
    filters=None,
    include=None,
    greedy=None,
    rerank_mult=None,
)
```

### Parameters

| Parameter       | Type         | Default                                   | Description                                                                                                                                                                                      |
| --------------- | ------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query_vectors` | `np.ndarray` | -                                         | A 1D array `(dim,)` for a single query, or a 2D array `(n_queries, dim)` for batch queries. The SDK casts to little-endian `float32` if needed.                                                  |
| `top_k`         | `int`        | `None` (server default: `100`)            | *(Optional)* Number of nearest neighbors to return per query.                                                                                                                                    |
| `n_probes`      | `int`        | `None` (auto)                             | *(Optional)* Number of clusters to probe. Higher = better recall, more latency.                                                                                                                  |
| `filters`       | `Dict`       | `None`                                    | *(Optional)* Metadata filter expression. See [metadata filtering](../../guides/data-operations/metadata-filtering).                                                                              |
| `include`       | `List[str]`  | `None` (server default returns only `id`) | *(Optional)* Subset of `"distance"`, `"metadata"`, `"vector"`. Unlike [`get`](./get), `"contents"` is **not** a valid value here — the query response model has no contents field.               |
| `greedy`        | `bool`       | `None`                                    | *(Optional)* Use the greedy approximate search algorithm.                                                                                                                                        |
| `rerank_mult`   | `int`        | `None` (server default: `10`)             | *(Optional)* Multiplier for stage 1 retrieval on reranking indexes. Stage 1 returns `top_k * rerank_mult` candidates before reranking narrows to `top_k`. Ignored by indexes that do not rerank. |

<Note>`include` defaults differ between endpoints: `query_binary` returns `[]` (only `id`) by default, while [`get`](./get) returns `["vector", "contents", "metadata"]`.</Note>

### Returns

* **Single query** (1D `query_vectors`): `List[Dict]` — one result dict per neighbor.
* **Batch query** (2D `query_vectors`): `List[List[Dict]]` — one inner list per query vector.

Each result dict contains `id` plus whichever of `distance`, `metadata`, `vector` were requested via `include`.

### Exceptions

<AccordionGroup>
  <Accordion title="Error">
    * `TypeError`: `query_vectors` is not a numpy array.
    * `ValueError`: `query_vectors.ndim` is not 1 or 2, or the server returns an error.
  </Accordion>
</AccordionGroup>

### Example Usage

#### Single query

```python theme={null}
import numpy as np

q = np.random.rand(384).astype(np.float32)
results = index.query_binary(q, top_k=5, include=["distance", "metadata"])
for r in results:
    print(r["id"], r["distance"])
```

#### Batch query

```python theme={null}
queries = np.random.rand(32, 384).astype(np.float32)
batch_results = index.query_binary(queries, top_k=10)
for i, results in enumerate(batch_results):
    print(f"Query {i}: {len(results)} hits")
```

<Tip>For ad-hoc queries and most application code, prefer [`query()`](./query) — it accepts either lists or numpy arrays and automatically routes to the binary path when numpy is supplied. Call `query_binary` directly only when you want to bypass the routing logic.</Tip>