---
title: "Query Rewriting"
description: "Improve search accuracy with automatic query expansion and rewriting"
---
Query rewriting automatically generates multiple variations of your search query to improve result coverage and accuracy. Supermemory creates several rewrites, searches through all of them, then merges and deduplicates the results.
## How Query Rewriting Works
When you enable `rewriteQuery: true`, Supermemory:
1. **Analyzes your original query** for intent and key concepts
2. **Generates multiple rewrites** with different phrasings and synonyms
3. **Executes searches** for both original and rewritten queries in parallel
4. **Merges and deduplicates** results from all queries
5. **Returns unified results** ranked by relevance
This process adds ~400ms latency but significantly improves result quality, especially for:
- **Natural language questions** ("How do neural networks learn?")
- **Ambiguous terms** that could have multiple meanings
- **Complex queries** with multiple concepts
- **Domain-specific terminology** that might have synonyms
## Basic Query Rewriting
```typescript
import Supermemory from 'supermemory';
const client = new Supermemory({
apiKey: process.env.SUPERMEMORY_API_KEY!
});
// Without query rewriting
const basicResults = await client.search.documents({
q: "How do transformers work in AI?",
rewriteQuery: false,
limit: 5
});
// With query rewriting - generates multiple query variations
const rewrittenResults = await client.search.documents({
q: "How do transformers work in AI?",
rewriteQuery: true,
limit: 5
});
console.log(`Basic search: ${basicResults.total} results`);
console.log(`Rewritten search: ${rewrittenResults.total} results`);
```
```python
from supermemory import Supermemory
import os
client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))
# Without query rewriting
basic_results = client.search.documents(
q="How do transformers work in AI?",
rewrite_query=False,
limit=5
)
# With query rewriting - generates multiple query variations
rewritten_results = client.search.documents(
q="How do transformers work in AI?",
rewrite_query=True,
limit=5
)
print(f"Basic search: {basic_results.total} results")
print(f"Rewritten search: {rewritten_results.total} results")
```
```bash
# Without query rewriting
echo "Basic search:"
curl -X POST "https://api.supermemory.ai/v3/search" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "How do transformers work in AI?",
"rewriteQuery": false,
"limit": 5
}' | jq '.total'
# With query rewriting
echo "Rewritten search:"
curl -X POST "https://api.supermemory.ai/v3/search" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "How do transformers work in AI?",
"rewriteQuery": true,
"limit": 5
}' | jq '.total'
```
**Sample Output Comparison:**
```json
// Without rewriting: 3 results
{
"results": [...],
"total": 3,
"timing": 120
}
// With rewriting: 8 results (found more relevant content)
{
"results": [...],
"total": 8,
"timing": 520 // +400ms for query processing
}
```
## Natural Language Questions
Query rewriting excels at converting conversational questions into effective search queries:
```typescript
// Natural language question
const results = await client.search.documents({
q: "What are the best practices for training deep learning models?",
rewriteQuery: true,
limit: 10
});
// The system might generate rewrites like:
// - "deep learning model training best practices"
// - "neural network training optimization techniques"
// - "machine learning model training guidelines"
// - "deep learning training methodology"
```
```python
# Natural language question
results = client.search.documents(
q="What are the best practices for training deep learning models?",
rewrite_query=True,
limit=10
)
# The system might generate rewrites like:
# - "deep learning model training best practices"
# - "neural network training optimization techniques"
# - "machine learning model training guidelines"
# - "deep learning training methodology"
```
```bash
curl -X POST "https://api.supermemory.ai/v3/search" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "What are the best practices for training deep learning models?",
"rewriteQuery": true,
"limit": 10
}'
```
**Sample Output:**
```json
{
"results": [
{
"documentId": "doc_123",
"title": "Deep Learning Training Guide",
"score": 0.92,
"chunks": [
{
"content": "Best practices for training deep neural networks include proper weight initialization, learning rate scheduling, and regularization techniques...",
"score": 0.89,
"isRelevant": true
}
]
},
{
"documentId": "doc_456",
"title": "Neural Network Optimization",
"score": 0.87,
"chunks": [
{
"content": "Effective training methodologies involve batch normalization, dropout, and gradient clipping to prevent overfitting...",
"score": 0.85,
"isRelevant": true
}
]
}
],
"total": 12,
"timing": 445
}
```
## Technical Term Expansion
Query rewriting helps find content using different technical terminologies:
```typescript
// Original query with specific terminology
const results = await client.search.documents({
q: "CNN architecture patterns",
rewriteQuery: true,
containerTags: ["research"],
limit: 8
});
// System expands to include:
// - "convolutional neural network architecture"
// - "CNN design patterns"
// - "convolutional network structures"
// - "CNN architectural components"
```
```python
# Original query with specific terminology
results = client.search.documents(
q="CNN architecture patterns",
rewrite_query=True,
container_tags=["research"],
limit=8
)
# System expands to include:
# - "convolutional neural network architecture"
# - "CNN design patterns"
# - "convolutional network structures"
# - "CNN architectural components"
```
```bash
curl -X POST "https://api.supermemory.ai/v3/search" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "CNN architecture patterns",
"rewriteQuery": true,
"containerTags": ["research"],
"limit": 8
}'
```
**Sample Output:**
```json
{
"results": [
{
"documentId": "doc_789",
"title": "Convolutional Neural Network Architectures",
"score": 0.94,
"chunks": [
{
"content": "Modern CNN architectures like ResNet and DenseNet utilize skip connections to address the vanishing gradient problem...",
"score": 0.91,
"isRelevant": true
}
]
},
{
"documentId": "doc_101",
"title": "Deep Learning Design Patterns",
"score": 0.88,
"chunks": [
{
"content": "Convolutional layers followed by pooling operations form the fundamental building blocks of CNN architectures...",
"score": 0.86,
"isRelevant": true
}
]
}
],
"total": 15,
"timing": 478
}
```
## Memory Search with Query Rewriting
Query rewriting works with both document and memory search:
```typescript
// Memory search with query rewriting
const memoryResults = await client.search.memories({
q: "explain quantum entanglement simply",
rewriteQuery: true,
containerTag: "physics_notes",
limit: 5
});
// Generates variations like:
// - "quantum entanglement explanation"
// - "what is quantum entanglement"
// - "quantum entanglement basics"
// - "simple quantum entanglement description"
```
```python
# Memory search with query rewriting
memory_results = client.search.memories(
q="explain quantum entanglement simply",
rewrite_query=True,
container_tag="physics_notes",
limit=5
)
# Generates variations like:
# - "quantum entanglement explanation"
# - "what is quantum entanglement"
# - "quantum entanglement basics"
# - "simple quantum entanglement description"
```
```bash
curl -X POST "https://api.supermemory.ai/v4/search" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "explain quantum entanglement simply",
"rewriteQuery": true,
"containerTag": "physics_notes",
"limit": 5
}'
```
**Sample Output:**
```json
{
"results": [
{
"id": "mem_456",
"memory": "Quantum entanglement is a phenomenon where two particles become connected in such a way that measuring one instantly affects the other, regardless of distance. Think of it like having two magical coins that always land on opposite sides.",
"similarity": 0.91,
"title": "Simple Quantum Entanglement Explanation",
"metadata": {
"topic": "quantum-physics",
"difficulty": "beginner"
}
},
{
"id": "mem_789",
"memory": "Einstein called quantum entanglement 'spooky action at a distance' because entangled particles seem to communicate instantaneously across vast distances, challenging our understanding of locality in physics.",
"similarity": 0.87,
"title": "Einstein's View on Entanglement"
}
],
"total": 7,
"timing": 412
}
```
## Complex Multi-Concept Queries
Query rewriting excels at handling queries with multiple concepts:
```typescript
const results = await client.search.documents({
q: "machine learning bias fairness algorithmic discrimination",
rewriteQuery: true,
filters: {
AND: [
{ key: "category", value: "ethics", negate: false }
]
},
limit: 10
});
// Breaks down into focused rewrites:
// - "machine learning bias detection"
// - "algorithmic fairness in AI"
// - "discrimination in machine learning algorithms"
// - "bias mitigation techniques ML"
```
```python
results = client.search.documents(
q="machine learning bias fairness algorithmic discrimination",
rewrite_query=True,
filters={
"AND": [
{"key": "category", "value": "ethics", "negate": False}
]
},
limit=10
)
# Breaks down into focused rewrites:
# - "machine learning bias detection"
# - "algorithmic fairness in AI"
# - "discrimination in machine learning algorithms"
# - "bias mitigation techniques ML"
```
```bash
curl -X POST "https://api.supermemory.ai/v3/search" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "machine learning bias fairness algorithmic discrimination",
"rewriteQuery": true,
"filters": {
"AND": [
{"key": "category", "value": "ethics", "negate": false}
]
},
"limit": 10
}'
```