> ## Documentation Index
> Fetch the complete documentation index at: https://cyborg-encryption-copy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Vectors

Retrieve the nearest neighbors for a given query vector.

## Authentication

Required - API key via `X-API-Key` header:

```http theme={null}
X-API-Key: cyborg_your_api_key_here
```

You can get an API key from the [CyborgDB Admin Dashboard](https://cyborgdb.co). For more info, follow [this guide](../../../intro/get-api-key).

## Request Body

### Single Query Request

```json theme={null}
{
  "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"]
}
```

### Batch Query Request

```json theme={null}
{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "query_vectors": [
    [0.1, 0.2, 0.3, 0.4],
    [0.5, 0.6, 0.7, 0.8]
  ],
  "top_k": 10,
  "n_probes": 1,
  "greedy": false,
  "filters": {"category": "greeting"},
  "include": ["distance", "metadata"]
}
```

### Semantic Search Request (with embedding model)

```json theme={null}
{
  "index_name": "semantic_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "query_contents": "Find documents about machine learning",
  "top_k": 10,
  "filters": {"type": "research"},
  "include": ["distance", "metadata"]
}
```

<Expandable title="parameters">
  <ParamField body="index_name" type="string" required="true">
    Name of the target index
  </ParamField>

  <ParamField body="index_key" type="string" required="true">
    32-byte encryption key as hex string
  </ParamField>

  <ParamField body="query_vectors" type="array[number] | array[array[number]]">
    Query vector(s) for similarity search:

    * Single query: `[0.1, 0.2, 0.3, ...]` (1D array)
    * Batch query: `[[0.1, 0.2, ...], [0.4, 0.5, ...]]` (2D array)
      Required unless `query_contents` is provided
  </ParamField>

  <ParamField body="query_contents" type="string">
    Text content for semantic search (requires index with `embedding_model`).
    Alternative to `query_vectors` for automatic embedding generation
  </ParamField>

  <ParamField body="top_k" type="integer" default={100}>
    Number of nearest neighbors to return
  </ParamField>

  <ParamField body="n_probes" type="integer" default="auto">
    Number of index lists to probe. When set to 0 or omitted, automatically determines optimal value based on index size and query requirements
  </ParamField>

  <ParamField body="greedy" type="boolean" default="false">
    Use greedy search for higher recall
  </ParamField>

  <ParamField body="filters" type="object">
    MongoDB-style metadata filters
  </ParamField>

  <ParamField body="include" type="array[string]" default={["distance", "metadata"]}>
    Fields to include in response:

    <Expandable title="include options">
      <ParamField body="distance" type="string">
        Include distance/similarity score to query vector
      </ParamField>

      <ParamField body="metadata" type="string">
        Include item metadata key-value pairs
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

## Response

### Single Query Response

When `query_vectors` is a 1D array or `query_contents` is used:

```json theme={null}
{
  "results": [
    {
      "id": "item_1",
      "distance": 0.123,
      "metadata": {"category": "greeting", "language": "en"}
    },
    {
      "id": "item_3",
      "distance": 0.245,
      "metadata": {"category": "greeting", "language": "es"}
    }
  ]
}
```

### Batch Query Response

When `query_vectors` is a 2D array (array of arrays):

```json theme={null}
{
  "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"}}
    ]
  ]
}
```

<Note>
  The response format automatically matches the request format:

  * Single query → flat array of results
  * Batch query → nested array with results for each query
</Note>

## Metadata Filtering

Use MongoDB-style query operators:

```json theme={null}
{
  "filters": {
    "$and": [
      {"category": "greeting"},
      {"confidence": {"$gte": 0.9}}
    ]
  }
}
```

**Supported operators:** `$and`, `$or`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`

## Exceptions

* `401`: Authentication failed (invalid API key)
* `404`: Index not found
* `422`: Invalid request parameters or vector dimensions
* `500`: Internal server error

## Example Usage

**Basic Query:**

```bash theme={null}
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
     }'
```

**With Filters:**

```bash theme={null}
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"]
     }'
```

**Semantic Search:**

```bash theme={null}
# 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"}
     }'
```

**Batch Query:**

```bash theme={null}
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"]
     }'
```

**High Recall Query:**

```bash theme={null}
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
     }'
```

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

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