> ## 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()` sends query vectors as base64-encoded little-endian `float32` instead of JSON arrays, which is faster for large batches. It accepts the same search and hybrid parameters as [`query()`](./query), except `query_contents`.

```python theme={null}
index.query_binary(
    query_vectors,
    top_k=None,
    n_probes=None,
    filters=None,
    include=None,
    greedy=None,
    rerank_mult=None,
    text=None,
    text_fields=None,
    text_field_weights=None,
    require_all_terms=None,
    alpha=None,
    rrf_k=None,
    window_mult=None,
)
```

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query_vectors` | `np.ndarray` | - | Shape `(dim,)` for one query or `(n_queries, dim)` for a batch. Cast to little-endian `float32` if needed. |
| `top_k` | `int` | `None` (service default: `100`) | *(Optional)* Results to return per query. Must be at least `1`. |
| `n_probes` | `int` | `None` (service default: auto) | *(Optional)* Clusters to probe. |
| `filters` | `Dict` | `None` | *(Optional)* Metadata filter. See [Metadata filtering](../types#metadata-filtering). |
| `include` | `List[str]` | `None` (service default: `[]`) | *(Optional)* Extra fields per result: `"distance"` and `"metadata"`. |
| `greedy` | `bool` | `None` (service default: `False`) | *(Optional)* Use greedy search. |
| `rerank_mult` | `int` | `None` (service default: `50`) | *(Optional)* Stage 1 candidate multiplier before reranking. |
| `text`, `text_fields`, `text_field_weights`, `require_all_terms`, `alpha`, `rrf_k`, `window_mult` | | `None` | *(Optional)* Hybrid search parameters. Same meaning and service defaults as on [`query()`](./query#parameters). |

### Returns

* **1-D `query_vectors`:** `List[Dict]`, one dict per neighbor.
* **2-D `query_vectors` with two or more rows:** `List[List[Dict]]`, one inner list per query vector. A 2-D array with one row returns a flat `List[Dict]`.

Each dict has `id`, plus `distance` (vector query) or `score` (hybrid query), and `metadata` when requested. As with [`query()`](./query#result-fields), `vector` and `contents` are not returned.

### Exceptions

<AccordionGroup>
  <Accordion title="cyborgdb.ValidationError">
    * Also a `TypeError`. `query_vectors` is not a NumPy array.
    * `query_vectors` is not 1-D or 2-D.
    * The service rejects the query (HTTP `400`/`422`), for example a wrong vector dimension.
  </Accordion>

  <Accordion title="cyborgdb.AuthenticationError">
    The `index_key` or `api_key` is invalid (HTTP `401`).
  </Accordion>

  <Accordion title="cyborgdb.ServiceError / cyborgdb.TransportError">
    The service returns `5xx` or can't be reached.
  </Accordion>
</AccordionGroup>

See [Errors](../errors) for the full hierarchy.

### Example Usage

#### Single query

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

q = np.array([0.1, 0.2, 0.3, 0.4], dtype=np.float32)
results = index.query_binary(q, top_k=2, include=["distance"])

for r in results:
    print(r["id"], round(r["distance"], 4))
# Output:
# doc1 0.0
# doc2 0.8
```

#### Batch query

```python theme={null}
queries = np.random.rand(32, 4).astype(np.float32)
batch_results = index.query_binary(queries, top_k=10)
print(len(batch_results))
# Output: 32
```

<Tip>[`query()`](./query) already uses this binary path when `query_vectors` is a NumPy array. Call `query_binary()` directly to make the choice explicit.</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.