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(), except query_contents.

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.
`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()`.

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(), vector and contents are not returned.

Exceptions

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.

cyborgdb.AuthenticationError

The index_key or api_key is invalid (HTTP 401).

cyborgdb.ServiceError / cyborgdb.TransportError

The service returns 5xx or can’t be reached.

See Errors for the full hierarchy.

Example Usage

Single query

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

queries = np.random.rand(32, 4).astype(np.float32)
batch_results = index.query_binary(queries, top_k=10)
print(len(batch_results))
# Output: 32

query() already uses this binary path when query_vectors is a NumPy array. Call query_binary() directly to make the choice explicit.

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