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
string
required
Name of the target index
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).
object
required
integer
Number of nearest neighbors to return per query. Defaults to 100
integer
Number of clusters to probe during search. Auto-determined when not specified
boolean
Whether to use greedy search algorithm. Defaults to false
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.object
Metadata filters to apply to the search
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 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