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

<CodeGroup>
  ```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 { 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}, ...]
  ```

  ```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
       }'
  ```
</CodeGroup>

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

<CodeGroup>
  ```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 { 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}}, ...]
  ```

  ```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"]
       }'
  ```
</CodeGroup>

## Batched Queries

It's also possible to perform batch queries by passing multiple query vectors to `query()`:

<CodeGroup>
  ```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 { 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]]
  ```

  ```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
       }'
  ```
</CodeGroup>

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

<Tip>To use automatic embedding generation, use the [Docker Service](../intro/quickstart-docker) or install with `pip install cyborgdb-service[embeddings]`</Tip>

If you provided an `embedding_model` during index creation, you can automatically generate embeddings for queries by providing `query_contents` to the `query()` call:

<CodeGroup>
  ```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 { 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);
  ```

  ```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
       }'
  ```
</CodeGroup>

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`:

<CodeGroup>
  ```python Python SDK icon="python" theme={null}
  # 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}, ...]
  ```

  ```javascript JavaScript SDK icon="js" theme={null}
  // 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}, ...]
  ```

  ```typescript TypeScript SDK icon="code" theme={null}
  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}, ...]
  ```

  ```go Go SDK icon="golang" theme={null}
  // 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}, ...]
  ```

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

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

<CodeGroup>
  ```python Python SDK icon="python" theme={null}
  results = index.query(
      query_vectors=query_vector,
      text="encrypted search",
      filters={"author": "ann"},  # resolved first; constrains both legs
      top_k=10,
  )
  ```

  ```javascript JavaScript SDK icon="js" theme={null}
  const response = await index.query({
      queryVectors: queryVector,
      text: "encrypted search",
      filters: { author: "ann" },  // resolved first; constrains both legs
      topK: 10,
  });
  ```

  ```typescript TypeScript SDK icon="code" theme={null}
  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);
  ```

  ```go Go SDK icon="golang" theme={null}
  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)
  }
  ```

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

<Note>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.</Note>

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](./bm25-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](./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](../advanced/train-index).

## API Reference

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

<CardGroup cols={2}>
  <Card title="REST API Reference" href="../../rest-api/encrypted-index/query" icon="rectangle-terminal">
    REST API reference for `/v1/vectors/query`
  </Card>

  <Card title="Python SDK Reference" href="../../python-sdk/encrypted-index/query" icon="python">
    API reference for `query()` in Python
  </Card>

  <Card title="JS/TS SDK Reference" href="../../js-ts-sdk/encrypted-index/query" icon="js">
    API reference for `query()` in JavaScript/TypeScript
  </Card>

  <Card title="Go SDK Reference" href="../../go-sdk/encrypted-index/query" icon="golang">
    API reference for `Query()` in Go
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.