Searching Documents

Search your RAG collections to find relevant information using semantic queries.

Basic Search

Using cURL

curl -X POST http://localhost/api/v1/rag/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "documentation",
    "query": "How do I reset my password?",
    "top_k": 5
  }'

Using Python

import requests

response = requests.post(
    "http://localhost/api/v1/rag/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "collection_name": "documentation",
        "query": "How do I reset my password?",
        "top_k": 5
    }
)

results = response.json()["results"]
for result in results:
    print(f"Score: {result['score']:.4f}")
    print(f"Content: {result['content'][:100]}...")
    print(f"Document: {result['metadata']['document_id']}\n")

Using JavaScript

const response = await fetch('http://localhost/api/v1/rag/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    collection_name: 'documentation',
    query: 'How do I reset my password?',
    top_k: 5
  })
});

const data = await response.json();
data.results.forEach(result => {
  console.log(`Score: ${result.score.toFixed(4)}`);
  console.log(`Content: ${result.content.substring(0, 100)}...\n`);
});

Search Parameters

Parameter	Type	Required	Description
collection_name	string	Yes	Collection to search
query	string	Yes	Search query
top_k	integer	No	Number of results (default: 5)
similarity_threshold	float	No	Minimum similarity (0-1, default: 0.5)
filters	object	No	Metadata filters

Search with Filters

response = requests.post(
    "http://localhost/api/v1/rag/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "collection_name": "policies",
        "query": "Data privacy guidelines",
        "top_k": 5,
        "filters": {
            "category": "legal",
            "version": "2.0"
        }
    }
)

results = response.json()["results"]
for result in results:
    print(f"Document: {result['metadata']['document_id']}")
    print(f"Category: {result['metadata']['category']}")

Similarity Threshold

Filter results by relevance score:

# Only return highly relevant results (90%+ similarity)
response = requests.post(
    "http://localhost/api/v1/rag/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "collection_name": "docs",
        "query": "API authentication",
        "top_k": 10,
        "similarity_threshold": 0.9
    }
)

results = response.json()["results"]
print(f"Found {len(results)} highly relevant results")

Threshold	Use Case
0.5-0.6	Broad exploration, many results
0.7-0.8	Standard search, balanced results
0.9-1.0	Precise matching, few results

Search Results Format

{
  "results": [
    {
      "score": 0.92,
      "content": "To reset your password, navigate to Settings > Security...",
      "metadata": {
        "document_id": "doc_123",
        "chunk_id": "chunk_456",
        "filename": "user_guide.pdf",
        "page": 15
      }
    }
  ],
  "query": "How do I reset my password?",
  "collection_name": "documentation"
}

Advanced Search Patterns

Fuzzy Search

Use natural language queries:

queries = [
    "How to configure API keys?",
    "API key setup instructions",
    "Where do I put my API key?",
    "Configure authentication for API"
]

for query in queries:
    response = requests.post(
        "http://localhost/api/v1/rag/search",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "collection_name": "docs",
            "query": query,
            "top_k": 3
        }
    )
    print(f"\nQuery: {query}")
    print(f"Results: {len(response.json()['results'])}")

Multi-Collection Search

Search across multiple collections:

collections = ["docs", "support", "faq"]
all_results = []

for collection in collections:
    response = requests.post(
        "http://localhost/api/v1/rag/search",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "collection_name": collection,
            "query": "How do I upgrade my plan?",
            "top_k": 3
        }
    )
    all_results.extend(response.json()["results"])

# Sort by score
all_results.sort(key=lambda x: x["score"], reverse=True)

print(f"Total results: {len(all_results)}")
for i, result in enumerate(all_results[:5], 1):
    print(f"{i}. Score: {result['score']:.2f} - {result['content'][:60]}...")

Hybrid Search with Filters

response = requests.post(
    "http://localhost/api/v1/rag/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "collection_name": "documentation",
        "query": "Security best practices",
        "top_k": 10,
        "similarity_threshold": 0.7,
        "filters": {
            "category": "security",
            "language": "en",
            "audience": "developers"
        }
    }
)

results = response.json()["results"]
for result in results:
    print(f"Score: {result['score']:.2f}")
    print(f"Category: {result['metadata']['category']}")
    print(f"Content: {result['content'][:80]}...\n")

Search Optimization

Optimize Query Quality

Good queries:

• "How do I configure API keys?"
• "Steps to reset user password"
• "Best practices for database optimization"

Poor queries:

• "API keys" (too vague)
• "configure" (too general)
• "setup thing" (ambiguous)

Use Appropriate Top-K

Scenario	Top-K
Quick answers	3-5
Research	5-10
Comprehensive analysis	10-20

Filter by Metadata

# Search specific document types
response = requests.post(
    "http://localhost/api/v1/rag/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "collection_name": "docs",
        "query": "API documentation",
        "filters": {
            "document_type": "api_reference",
            "version": "2.0"
        }
    }
)

Search Error Handling

import requests
from requests.exceptions import RequestException

def safe_search(collection_name, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "http://localhost/api/v1/rag/search",
                headers={"Authorization": "Bearer YOUR_API_KEY"},
                json={
                    "collection_name": collection_name,
                    "query": query,
                    "top_k": 5
                },
                timeout=10
            )
            response.raise_for_status()
            return response.json()
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            print(f"Attempt {attempt + 1} failed. Retrying...")
            time.sleep(1)

result = safe_search("docs", "API configuration")

Search Performance Tips

1. Use specific queries - More specific = better results
2. Set appropriate top-k - Avoid unnecessary data retrieval
3. Use filters - Narrow down results by metadata
4. Adjust similarity threshold - Balance precision and recall
5. Cache results - Cache frequent searches

Troubleshooting

No Results Found

Problem: Search returns empty results

Solution:

• Verify collection name is correct
• Check collection has documents
• Lower similarity_threshold
• Increase top_k value
• Try broader query terms

Low Quality Results

Problem: Results don't match query well

Solution:

• Refine query terms
• Check document content matches query
• Increase top_k to get more options
• Review document chunking strategy
• Update documents with better keywords

Slow Search Performance

Problem: Search takes too long

Solution:

• Reduce top_k value
• Use metadata filters
• Check vector database performance
• Review collection size
• Consider indexing improvements

Collection Not Found

Problem: {"error": "Collection not found"}

Solution:

• Verify collection name spelling
• Check collection exists using list endpoint
• Confirm you have access to collection

Next Steps

• Manage Documents - List and delete documents
• RAG Chat Examples - Combine search with chat
• Examples - More search examples