Encrypted Index
Query Vectors (Binary)
POST
/
v1
/
vectors
/
query_binary
Query Vectors (Binary)
curl --request POST \
--url https://api.example.com/v1/vectors/query_binaryimport requests
url = "https://api.example.com/v1/vectors/query_binary"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v1/vectors/query_binary', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/vectors/query_binary",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/vectors/query_binary"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/vectors/query_binary")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/vectors/query_binary")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodySearch for nearest neighbors in the encrypted index using binary-encoded query vectors for more efficient transfer of large batch queries.
You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.
Authentication
Required - API key viaX-API-Key header:
X-API-Key: cyborg_your_api_key_here
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
Show parameters
Name of the target index
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).
Number of nearest neighbors to return per query. Defaults to 100
Number of clusters to probe during search. Auto-determined when not specified
Whether to use greedy search algorithm. Defaults to false
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.Metadata filters to apply to the search
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 wrongindex_keyon SDK-supplied indexes — see error model404: Index not found422: Invalid request parameters or vector dimensions500: 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).Was this page helpful?
⌘I