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.

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.
`include`	`List[str]`	`None` (server default returns only `id`)	(Optional) Subset of `"distance"`, `"metadata"`, `"vector"`. Unlike `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.

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

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

Error

TypeError: query_vectors is not a numpy array.
ValueError: query_vectors.ndim is not 1 or 2, or the server returns an error.

Example Usage

Single query

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

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")

For ad-hoc queries and most application code, prefer 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.

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Returns

Exceptions

Example Usage

Single query

Batch query

​Parameters

​Returns

​Exceptions

​Example Usage

​Single query

​Batch query

Parameters

Returns

Exceptions

Example Usage

Single query

Batch query