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():

# 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}, ...]

// 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}, ...]

import { QueryResponse } from 'cyborgdb';

// Example query
const queryVectors: number[] = [0.5, 0.9, 0.2, 0.7];
const topK: number = 10;

// Perform query
const params = { 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}, ...]

// 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}, ...]

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).

# 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}}, ...]

// 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}}, ...]

import { 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 = {
    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}}, ...]

// 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}}, ...]

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():

# 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]]

// 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]]

import { 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 = {
    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]]

// 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]]

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:

{"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 guide.

Automatic Embedding Generation

To use automatic embedding generation, use the Docker Service 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:

# ... 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)

// ... 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
});

import { 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 = {
    queryContents,
    topK
};
const response: QueryResponse = await index.query(params);

// 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)

# 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.

Hybrid Search (BM25 + Vector)

If the index was created with at least one full_text metadata field, passing text alongside query_vectors turns the query into a hybrid query: BM25 full-text ranking is fused with the vector ranking, and each result carries a score (fused relevance, larger = better) instead of a distance:

# Requires an index created with text_fields=[...] (or full_text in metadata_schema)
results = index.query(
    query_vectors=query_vector,
    text="encrypted search",
    top_k=10,
    alpha=0.5,  # 0 = pure BM25, 1 = pure vector; default 0.5
)
# [{"id": "a1", "score": 0.0161}, ...]

// Requires an index created with textFields (or fullText in metadataSchema)
const queryVector = [0.5, 0.9, 0.2, 0.7];

const response = await index.query({
    queryVectors: queryVector,
    text: "encrypted search",
    topK: 10,
    alpha: 0.5,  // 0 = pure BM25, 1 = pure vector; default 0.5
});
// [{id: "a1", score: 0.0161}, ...]

import { QueryResponse } from 'cyborgdb';

// Requires an index created with textFields (or fullText in metadataSchema)
const queryVector: number[] = [0.5, 0.9, 0.2, 0.7];

const params = {
    queryVectors: queryVector,
    text: "encrypted search",
    topK: 10,
    alpha: 0.5,  // 0 = pure BM25, 1 = pure vector; default 0.5
};
const response: QueryResponse = await index.query(params);
// [{id: "a1", score: 0.0161}, ...]

// Requires an index created with TextFields (or full_text in MetadataSchema)
params := cyborgdb.QueryParams{
    QueryVector: queryVector,
    Text:        cyborgdb.String("encrypted search"),
    TopK:        int32(10),
    Alpha:       cyborgdb.Float64(0.5), // 0 = pure BM25, 1 = pure vector
}

results, err := index.Query(context.Background(), params)
if err != nil {
    log.Fatal(err)
}
// [{"id": "a1", "score": 0.0161}, ...]

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],
       "text": "encrypted search",
       "top_k": 10,
       "alpha": 0.5
     }'

Adding filters on top composes a three-way query (vector + BM25 + metadata). The filter is resolved first, and both legs rank only its survivors:

results = index.query(
    query_vectors=query_vector,
    text="encrypted search",
    filters={"author": "ann"},  # resolved first; constrains both legs
    top_k=10,
)

const response = await index.query({
    queryVectors: queryVector,
    text: "encrypted search",
    filters: { author: "ann" },  // resolved first; constrains both legs
    topK: 10,
});

import { QueryResponse } from 'cyborgdb';

const params = {
    queryVectors: queryVector,
    text: "encrypted search",
    filters: { author: "ann" },  // resolved first; constrains both legs
    topK: 10,
};
const response: QueryResponse = await index.query(params);

params := cyborgdb.QueryParams{
    QueryVector: queryVector,
    Text:        cyborgdb.String("encrypted search"),
    // Resolved first; constrains both legs.
    Filters: map[string]interface{}{"author": "ann"},
    TopK:    int32(10),
}

results, err := index.Query(context.Background(), params)
if err != nil {
    log.Fatal(err)
}

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],
       "text": "encrypted search",
       "filters": {"author": "ann"},
       "top_k": 10
     }'

A query with text set accepts only filters the metadata index can resolve exactly — $regex on a non-pattern field, or any predicate on a filterable: false field, is rejected once text is present.

For full-text search without a vector, field designation at index creation, tuning knobs (alpha, rrf_k, window_mult), and constraints, see the Full-Text and Hybrid Search guide.

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 guide.

Index Training for Optimal Performance

Training improves query speed and accuracy. The CyborgDB service trains your index automatically once it holds enough vectors (more than 65,536 by default) and retrains it as it grows, so you usually don’t need to train it yourself. Until the index is trained, queries use exhaustive search, which is fine for small datasets. You can also train explicitly, for example to choose training parameters. For more details, see Training an Encrypted Index.

API Reference

For more information on querying encrypted indexes, refer to the API reference:

REST API Reference

REST API reference for /v1/vectors/query

Python SDK Reference

API reference for query() in Python

JS/TS SDK Reference

API reference for query() in JavaScript/TypeScript

Go SDK Reference

API reference for Query() in Go

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

Query Parameters

Batched Queries

Querying with Metadata Filters

Automatic Embedding Generation

Hybrid Search (BM25 + Vector)

Retrieving Items Post-Query

Index Training for Optimal Performance

API Reference

REST API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

​Query Parameters

​Batched Queries

​Querying with Metadata Filters

​Automatic Embedding Generation

​Hybrid Search (BM25 + Vector)

​Retrieving Items Post-Query

​Index Training for Optimal Performance

​API Reference

REST API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

Query Parameters

Batched Queries

Querying with Metadata Filters

Automatic Embedding Generation

Hybrid Search (BM25 + Vector)

Retrieving Items Post-Query

Index Training for Optimal Performance

API Reference