Query Vectors (Binary) - CyborgDB Docs

Search for nearest neighbors in the encrypted index using binary-encoded query vectors for more efficient transfer of large batch queries.

Authentication

Required - API key via X-API-Key header:

X-API-Key: cyborg_your_api_key_here

You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.

Request Body

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "batch": {
    "vectors_b64": "BASE64_ENCODED_FLOAT32_ARRAY",
    "dimension": 384
  },
  "top_k": 10,
  "n_probes": 5,
  "greedy": false,
  "rerank_mult": 10,
  "filters": {"category": "research"},
  "include": ["distance", "metadata"]
}

Show parameters

index_name

string

required

Name of the target index

index_key

string

32-byte encryption key as a hex string. Required for indexes created with the SDK-supplied KEK path; omit for KMS-backed indexes (the service resolves the key via the stored KMSBlob).

batch

object

required

Batch of query vectors in binary format:

Show batch parameters

vectors_b64

string

required

Base64-encoded float32 array. The decoded bytes represent a flat array of n_queries x dimension little-endian float32 values

dimension

integer

required

Dimensionality of each query vector

top_k

integer

Number of nearest neighbors to return per query. Defaults to 100

n_probes

integer

Number of clusters to probe during search. Auto-determined when not specified

greedy

boolean

Whether to use greedy search algorithm. Defaults to false

rerank_mult

integer

default:10

Multiplier for stage 1 retrieval in reranking indexes. Stage 1 returns top_k * rerank_mult candidates before the rerank pass narrows the result down to top_k. Higher values trade query latency for recall. Ignored by indexes that do not rerank.

filters

object

Metadata filters to apply to the search

include

array[string]

Fields to include in response: "distance", "metadata", "vector". Defaults to [] (only id is returned). "contents" is not a valid value — fetch contents via POST /v1/vectors/get with the matching IDs afterwards.

Response

The response format is the same as the standard query endpoint:

{
  "results": [
    [
      {"id": "doc1", "distance": 0.125, "metadata": {"category": "research"}},
      {"id": "doc2", "distance": 0.234, "metadata": {"category": "research"}}
    ],
    [
      {"id": "doc3", "distance": 0.156, "metadata": {"category": "research"}},
      {"id": "doc4", "distance": 0.278, "metadata": {"category": "research"}}
    ]
  ]
}

Exceptions

401: Authentication failed (invalid API key) or wrong index_key on SDK-supplied indexes — see error model
404: Index not found
422: Invalid request parameters or vector dimensions
500: Internal server error

Example Usage

# Encode query vectors as base64 float32 array (example using Python)
# query_vectors = np.array([[0.1, 0.2, 0.3, 0.4]], dtype=np.float32)
# vectors_b64 = base64.b64encode(query_vectors.tobytes()).decode()

curl -X POST "http://localhost:8000/v1/vectors/query_binary" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "batch": {
         "vectors_b64": "zczMPc3MTD6amZk+zczMPg==",
         "dimension": 4
       },
       "top_k": 5
     }'

The binary format is more efficient than the standard JSON query for large batch queries, as it avoids the overhead of encoding each float as a JSON number. The SDK clients automatically use this format when query vectors are passed as typed arrays (e.g., np.ndarray in Python, Float32Array in JS/TS).

​Authentication

​Request Body

​Response

​Exceptions

​Example Usage

Authentication

Request Body

Response

Exceptions

Example Usage