> ## 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
Searches for nearest neighbors in the encrypted index using vector similarity search. Supports single vector queries, batch queries, and semantic search with text content.
```python theme={null}
# Single vector query
index.query(query_vectors=vector, top_k=10)
# Batch vector queries
index.query(query_vectors=vectors, top_k=10)
# Semantic search with text
index.query(query_contents=text, top_k=10)
```
### Parameters
| Parameter | Type | Default | Description |
| ---------------- | ---------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query_vectors` | `List[List[float]]` or `List[float]` or `np.ndarray` | `None` | *(Optional)* Multiple query vectors for batch search |
| `query_contents` | `str` | `None` | *(Optional)* Text content for semantic search |
| `top_k` | `int` | `None` (server default: `100`) | *(Optional)* Number of results to return per query. |
| `n_probes` | `int` | `None` | *(Optional)* Number of clusters to probe for search |
| `filters` | `Dict` | `None` | *(Optional)* Metadata filters to apply |
| `include` | `List[str]` | `None` | *(Optional)* Fields to include in results. `None` uses the server default (`[]` — only `id` is returned). Note: `id` is always included |
| `greedy` | `bool` | `None` (server default: `false`) | *(Optional)* Use greedy search algorithm. |
| `rerank_mult` | `int` | `None` | *(Optional)* Multiplier for stage 1 retrieval in reranking indexes. Stage 1 returns `top_k * rerank_mult` candidates before the rerank pass narrows to `top_k`. Higher values trade query latency for recall. Server default is `10`. Ignored by indexes that do not rerank. |
When `np.ndarray` is passed as `query_vectors`, queries are automatically sent in an optimized binary format for better performance.
`include` defaults differ between endpoints: `query` returns `[]` (only `id`) by default, while [`get`](./get) returns `["vector", "contents", "metadata"]`.
### Returns
For single queries: `List[Dict]` - A list of result dictionaries.
For batch queries: `List[List[Dict]]` - A list of result lists, one for each query vector.
#### Result Format
**Single Query Result:**
```python theme={null}
[ # Returns a flat list of results
{
"id": str, # Vector identifier (always included)
"distance": float, # Similarity distance (if included)
"metadata": Dict, # Vector metadata (if included)
"contents": str, # Vector contents (if included)
"vector": List[float] # Vector data (if included)
},
...
]
```
**Batch Query Result:**
```python theme={null}
[
[ # Results for first query vector
{
"id": str,
"distance": float,
"metadata": Dict,
...
},
...
],
[ # Results for second query vector
...
],
...
]
```
### Exceptions
* Throws if the API request fails due to network connectivity issues.
* Throws if authentication fails (invalid API key).
* Throws if the encryption key is invalid for the specified index.
* Throws if there are internal server errors during the search.
* Throws if query vectors or query contents is not provided.
* Throws if vector dimensions don't match the index configuration.
* Throws if parameter values are out of valid ranges.
* Throws if the `include` parameter contains invalid field names.
### Example Usage
#### Single Vector Query
```python theme={null}
# Basic similarity search
query_vector = [0.1, 0.2, 0.3, 0.4]
# include defaults to [] (only `id`); pass include to request additional fields
results = index.query(query_vectors=query_vector, top_k=5, include=["distance", "metadata"])
# Access results (single query returns a flat list)
for result in results:
print(f"ID: {result['id']}, Distance: {result['distance']}")
```
Batch vector queries:
```python theme={null}
import numpy as np
# Query multiple vectors at once
query_vectors = [
[0.1, 0.2, 0.3, 0.4],
[0.5, 0.6, 0.7, 0.8],
[0.9, 1.0, 1.1, 1.2]
]
# include defaults to [] (only `id`); pass include to request additional fields
batch_results = index.query(query_vectors=query_vectors, top_k=3, include=["distance"])
# Process each query's results
for i, query_results in enumerate(batch_results):
print(f"Results for query {i+1}:")
for result in query_results:
print(f" ID: {result['id']}, Distance: {result['distance']}")
```
#### Semantic Search with Text
```python theme={null}
# Search using text content
results = index.query(
query_contents="machine learning healthcare applications",
top_k=10,
include=["contents"]
)
for result in results:
print(f"Found: {result['id']}")
if 'contents' in result:
print(f"Content: {result['contents'][:100]}...")
```
Advanced filtering and options:
```python theme={null}
# Query with metadata filters and custom options
results = index.query(
query_vectors=[0.1] * 384,
top_k=20,
n_probes=5, # Search more clusters for better recall
rerank_mult=20, # Stage 1 returns top_k * 20 candidates before rerank
filters={'category': 'healthcare', 'priority': 'high'},
include=['distance', 'metadata', 'contents'], # Must include 'contents' to access it
greedy=True # Use greedy search for potentially better results
)
for result in results:
print(f"ID: {result['id']}")
print(f"Distance: {result['distance']:.4f}")
print(f"Category: {result['metadata']['category']}")
print(f"Content preview: {result['contents'][:50]}...")
print("---")
```