Encrypted Index
Query Vectors
POST
/
v1
/
vectors
/
query
Query Vectors
curl --request POST \
--url https://api.example.com/v1/vectors/queryimport requests
url = "https://api.example.com/v1/vectors/query"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v1/vectors/query', 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",
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"
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")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/vectors/query")
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_bodyRetrieve the nearest neighbors for a given query vector.
You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.
Batch Query:
Supported operators:
With Filters:
Semantic Search:
Batch Query:
High Recall Query:
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",
"query_vectors": [0.1, 0.2, 0.3, 0.4],
"top_k": 10,
"n_probes": 1,
"greedy": false,
"filters": {"category": "greeting"},
"include": ["distance", "metadata"]
}
Show parameters
Show parameters
string
required
Name of the target index
string
required
32-byte encryption key as hex string
array[number]
required
List of query vectors (single vector for single query, array for batch query)
integer
default:100
Number of nearest neighbors to return
integer
default:1
Number of index lists to probe (higher = more recall)
boolean
default:"false"
Use greedy search for higher recall
object
MongoDB-style metadata filters
Response
Single Query:{
"results": [
{
"id": "item_1",
"distance": 0.123,
"metadata": {"category": "greeting", "language": "en"}
},
{
"id": "item_3",
"distance": 0.245,
"metadata": {"category": "greeting", "language": "es"}
}
]
}
{
"results": [
[
{"id": "item_1", "distance": 0.123, "metadata": {"category": "greeting"}},
{"id": "item_2", "distance": 0.245, "metadata": {"category": "farewell"}}
],
[
{"id": "item_3", "distance": 0.156, "metadata": {"category": "question"}},
{"id": "item_4", "distance": 0.298, "metadata": {"category": "answer"}}
]
]
}
Metadata Filtering
Use MongoDB-style query operators:{
"filters": {
"$and": [
{"category": "greeting"},
{"confidence": {"$gte": 0.9}}
]
}
}
$and, $or, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
Exceptions
401: Authentication failed (invalid API key)404: Index not found422: Invalid request parameters or vector dimensions500: Internal server error
Example Usage
Basic Query:curl -X POST "http://localhost:8000/v1/vectors/query" \
-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",
"query_vectors": [0.1, 0.2, 0.3, 0.4],
"top_k": 5
}'
curl -X POST "http://localhost:8000/v1/vectors/query" \
-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",
"query_vectors": [0.1, 0.2, 0.3, 0.4],
"top_k": 10,
"filters": {
"$and": [
{"category": "document"},
{"priority": {"$gte": 3}}
]
},
"include": ["distance", "metadata"]
}'
# For indexes with embedding_model
curl -X POST "http://localhost:8000/v1/vectors/query" \
-H "X-API-Key: cyborg_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"index_name": "semantic_index",
"index_key": "your_64_character_hex_key_here",
"query_contents": "Find documents about machine learning",
"top_k": 10,
"filters": {"type": "research"}
}'
curl -X POST "http://localhost:8000/v1/vectors/query" \
-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",
"query_vectors": [
[0.1, 0.2, 0.3, 0.4],
[0.5, 0.6, 0.7, 0.8],
[0.9, 0.1, 0.2, 0.3]
],
"top_k": 5,
"include": ["distance"]
}'
curl -X POST "http://localhost:8000/v1/vectors/query" \
-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",
"query_vectors": [0.1, 0.2, 0.3, 0.4],
"top_k": 20,
"n_probes": 10,
"greedy": true
}'
If
embedding_model is configured for the index, you can use either query_vectors for direct vector search or query_contents for text-based semantic search.Higher
n_probes values and greedy=true increase recall but may reduce query performance. Start with default values and adjust based on your recall requirements.Was this page helpful?
⌘I