> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Query Encrypted Index
Once you've added items to an encrypted index, you can query the index to retrieve the items that match a given query. This is done via `query()`:
```python Python SDK icon="python" theme={null}
# Example query
query_vector = [0.5, 0.9, 0.2, 0.7]
top_k = 10
# Perform query
results = index.query(query_vectors=query_vector, top_k=top_k)
print(results)
# Example results (flat list for single query)
# [{"id": "item_12", "distance": 0.01}, {"id": "item_7", "distance": 0.04}, ...]
```
```javascript JavaScript SDK icon="js" theme={null}
// Example query
const queryVectors = [0.5, 0.9, 0.2, 0.7];
const topK = 10;
// Perform query
const response = await index.query({ queryVectors, topK });
console.log(response.results);
// Example results (flat list for single query)
// [{id: "item_12", distance: 0.01}, {id: "item_7", distance: 0.04}, ...]
```
```typescript TypeScript SDK icon="code" theme={null}
import { QueryRequest, QueryResponse } from 'cyborgdb';
// Example query
const queryVectors: number[] = [0.5, 0.9, 0.2, 0.7];
const topK: number = 10;
// Perform query
const params: QueryRequest = { queryVectors, topK };
const response: QueryResponse = await index.query(params);
console.log(response.results);
// Example results (flat list for single query)
// [{id: "item_12", distance: 0.01}, {id: "item_7", distance: 0.04}, ...]
```
```go Go SDK icon="golang" theme={null}
// Example query
queryVector := []float32{0.5, 0.9, 0.2, 0.7}
params := cyborgdb.QueryParams{
QueryVector: queryVector,
TopK: int32(10),
Include: []string{"distance"},
}
// Perform query
results, err := index.Query(context.Background(), params)
if err != nil {
log.Fatal(err)
}
fmt.Println(results)
// Example results (flat list for single query)
// [{"id": "item_12", "distance": 0.01}, {"id": "item_7", "distance": 0.04}, ...]
```
```bash cURL icon="rectangle-terminal" theme={null}
curl -X POST "http://localhost:8000/v1/vectors/query" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"index_name": "my_index",
"index_key": "your_64_character_hex_key_here",
"query_vectors": [0.5, 0.9, 0.2, 0.7],
"top_k": 10
}'
```
## Query Parameters
You can specify additional parameters for the query, such as:
* `top_k`: the number of results to return. Default: `100`.
* `n_probes`: the number of clusters to search for each query vector. Default: `None` (auto-determined by server).
* `filters`: metadata filters to apply to the query (dictionary format). Default: `None`.
* `include`: item fields to return (e.g., `["distance", "metadata"]`). Default: `[]` (only `id` is returned). Note: `id` is always included.
* `greedy`: whether to use faster approximate search. Default: `None` (server default: `false`).
```python Python SDK icon="python" theme={null}
# Example query with parameters
query_vector = [0.5, 0.9, 0.2, 0.7]
top_k = 10
n_probes = 5
filters = {"age": {"$gt": 18}}
include = ["distance", "metadata"]
# Perform query
results = index.query(
query_vectors=query_vector,
top_k=top_k,
n_probes=n_probes,
filters=filters,
include=include
)
print(results)
# Example results (flat list for single query)
# [{"id": "item_12", "distance": 0.01, "metadata": {"age": 25}}, ...]
```
```javascript JavaScript SDK icon="js" theme={null}
// Example query with parameters
const queryVectors = [0.5, 0.9, 0.2, 0.7];
const topK = 10;
const nProbes = 5;
const filters = {age: {$gt: 18}};
const include = ["distance", "metadata"];
// Perform query
const response = await index.query({
queryVectors,
topK,
nProbes,
filters,
include
});
console.log(response.results);
// Example results (flat list for single query)
// [{id: "item_12", distance: 0.01, metadata: {age: 25}}, ...]
```
```typescript TypeScript SDK icon="code" theme={null}
import { QueryRequest, QueryResponse, FilterExpression } from 'cyborgdb';
// Example query with parameters
const queryVectors: number[] = [0.5, 0.9, 0.2, 0.7];
const topK: number = 10;
const nProbes: number = 5;
const filters: FilterExpression = {age: {$gt: 18}};
const include: string[] = ["distance", "metadata"];
// Perform query
const params: QueryRequest = {
queryVectors,
topK,
nProbes,
filters,
include
};
const response: QueryResponse = await index.query(params);
console.log(response.results);
// Example results (flat list for single query)
// [{id: "item_12", distance: 0.01, metadata: {age: 25}}, ...]
```
```go Go SDK icon="golang" theme={null}
// Example query with parameters
queryVector := []float32{0.5, 0.9, 0.2, 0.7}
nProbes := int32(5)
params := cyborgdb.QueryParams{
QueryVector: queryVector,
TopK: int32(10),
NProbes: &nProbes,
Filters: map[string]interface{}{"age": map[string]interface{}{"$gt": 18}},
Include: []string{"distance", "metadata"},
}
// Perform query
results, err := index.Query(context.Background(), params)
if err != nil {
log.Fatal(err)
}
fmt.Println(results)
// Example results (flat list for single query)
// [{"id": "item_12", "distance": 0.01, "metadata": {"age": 25}}, ...]
```
```bash cURL icon="rectangle-terminal" theme={null}
curl -X POST "http://localhost:8000/v1/vectors/query" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"index_name": "my_index",
"index_key": "your_64_character_hex_key_here",
"query_vectors": [0.5, 0.9, 0.2, 0.7],
"top_k": 10,
"n_probes": 5,
"filters": {
"age": {"$gt": 18}
},
"include": ["distance", "metadata"]
}'
```
## Batched Queries
It's also possible to perform batch queries by passing multiple query vectors to `query()`:
```python Python SDK icon="python" theme={null}
# Example batch query
query_vectors = [[0.5, 0.9, 0.2, 0.7], [0.1, 0.3, 0.8, 0.6]]
top_k = 10
# Perform batch query
results = index.query(
query_vectors=query_vectors,
top_k=top_k
)
print(results)
# Returns nested results: one list per query vector
# [[results_for_query_1], [results_for_query_2]]
```
```javascript JavaScript SDK icon="js" theme={null}
// Example batch query
const queryVectors = [[0.5, 0.9, 0.2, 0.7], [0.1, 0.3, 0.8, 0.6]];
const topK = 10;
// Perform batch query
const response = await index.query({
queryVectors,
topK
});
console.log(response.results);
// Returns nested results: one list per query vector
// [[results_for_query_1], [results_for_query_2]]
```
```typescript TypeScript SDK icon="code" theme={null}
import { QueryRequest, QueryResponse } from 'cyborgdb';
// Example batch query
const queryVectors: number[][] = [[0.5, 0.9, 0.2, 0.7], [0.1, 0.3, 0.8, 0.6]];
const topK: number = 10;
// Perform batch query
const params: QueryRequest = {
queryVectors,
topK
};
const response: QueryResponse = await index.query(params);
console.log(response.results);
// Returns nested results: one list per query vector
// [[results_for_query_1], [results_for_query_2]]
```
```go Go SDK icon="golang" theme={null}
// Example batch query
queryVectors := [][]float32{
{0.5, 0.9, 0.2, 0.7},
{0.1, 0.3, 0.8, 0.6},
}
params := cyborgdb.QueryParams{
BatchQueryVectors: queryVectors,
TopK: int32(10),
}
// Perform batch query
results, err := index.Query(context.Background(), params)
if err != nil {
log.Fatal(err)
}
fmt.Println(results)
// Returns nested results: one list per query vector
// [[results_for_query_1], [results_for_query_2]]
```
```bash cURL icon="rectangle-terminal" theme={null}
curl -X POST "http://localhost:8000/v1/vectors/query" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"index_name": "my_index",
"index_key": "your_64_character_hex_key_here",
"query_vectors": [
[0.5, 0.9, 0.2, 0.7],
[0.1, 0.3, 0.8, 0.6]
],
"top_k": 10
}'
```
## Querying with Metadata Filters
You can filter query results based on metadata fields. For example, to filter items where the `age` field is greater than `18`, you can use the following filter:
```json theme={null}
{"age": {"$gt": 18}}
```
This filter will return items where the `age` field is greater than `18`. You can also use other comparison operators such as `$lt`, `$gte`, `$lte`, `$eq`, and `$ne`.
For more details on metadata filters, see the [Metadata Filtering](./metadata-filtering) guide.
## Automatic Embedding Generation
To use automatic embedding generation, use the [Docker Service](../intro/quickstart-docker) or install with `pip install cyborgdb-service[embeddings]`
If you provided an `embedding_model` during index creation, you can automatically generate embeddings for queries by providing `query_contents` to the `query()` call:
```python Python SDK icon="python" theme={null}
# ... index creation and embedding model setup
embedding_model = "all-MiniLM-L6-v2"
index = client.create_index("my_index", index_key=index_key, embedding_model=embedding_model)
# ... Add items to the encrypted index ...
# Example semantic query
query_contents = "What is the capital of France?"
top_k = 10
# Perform query
results = index.query(query_contents=query_contents, top_k=top_k)
```
```javascript JavaScript SDK icon="js" theme={null}
// ... index creation and embedding model setup
const embeddingModel = "all-MiniLM-L6-v2";
const index = await client.createIndex({ indexName: "my_index", indexKey, embeddingModel });
// ... Add items to the encrypted index ...
// Example semantic query
const queryContents = "What is the capital of France?";
const topK = 10;
// Perform query
const results = await index.query({
queryContents,
topK
});
```
```typescript TypeScript SDK icon="code" theme={null}
import { QueryRequest, QueryResponse, EncryptedIndex } from 'cyborgdb';
// ... index creation and embedding model setup
const embeddingModel: string = "all-MiniLM-L6-v2";
const index: EncryptedIndex = await client.createIndex({ indexName: "my_index", indexKey, embeddingModel });
// ... Add items to the encrypted index ...
// Example semantic query
const queryContents: string = "What is the capital of France?";
const topK: number = 10;
// Perform query
const params: QueryRequest = {
queryContents,
topK
};
const response: QueryResponse = await index.query(params);
```
```go Go SDK icon="golang" theme={null}
// Example semantic query
queryContents := "What is the capital of France?"
params := cyborgdb.QueryParams{
QueryContents: &queryContents,
TopK: int32(10),
}
// Perform query
results, err := index.Query(context.Background(), params)
if err != nil {
log.Fatal(err)
}
fmt.Println(results)
```
```bash cURL icon="rectangle-terminal" theme={null}
# For indexes with embedding_model
curl -X POST "http://localhost:8000/v1/vectors/query" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"index_name": "my_index",
"index_key": "your_64_character_hex_key_here",
"query_contents": "What is the capital of France?",
"top_k": 10
}'
```
This feature allows you to perform semantic search using natural language queries. The service will automatically generate embeddings for your query text using the specified embedding model.
## Retrieving Items Post-Query
In certain applications, such as RAG, it may be desirable to retrieve matching items after a query. This is possible via `get()`, which retrieves and decrypts item added via `upsert()`. For more details, see the [Get Items](./get-items) guide.
## Index Training for Optimal Performance
For optimal query performance, you should train your index after adding a significant amount of data (typically more than 50,000 vectors). The CyborgDB service supports index training to improve query speed and accuracy.
Queries will initially use exhaustive search, which is fine for small datasets. Once you have a substantial amount of data, train the index for better performance. For more details, see [Training an Encrypted Index](../advanced/train-index).
## API Reference
For more information on querying encrypted indexes, refer to the API reference:
REST API reference for `/v1/vectors/query`
API reference for `query()` in Python
API reference for `query()` in JavaScript/TypeScript
API reference for `Query()` in Go