Search Guide

Learn how to perform semantic and hybrid search across your documents using RAGaaS.

Overview

RAGaaS provides powerful semantic and hybrid search capabilities that understand the meaning behind queries, not just keywords.

The search process:

1. Query is converted to a vector using the same embedding model as your content
2. System searches for similar vectors in your namespace
3. Metadata filters are applied
4. Results are ranked by similarity
5. Top results are returned

Configuration

Senantic Search

curl -X POST "https://api.ragaas.dev/v1/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How to implement authentication?",
    "namespaceId": "docs",
    "topK": 5,
    "scoreThreshold": 0.7
  }'

Hybrid Search

curl -X POST "https://api.ragaas.dev/v1/search/hybrid" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Connection refused error postgres",
    "namespaceId": "docs",
    "topK": 3,
    "scoreThreshold": 0.5,
    "hybridConfig": {
      "semanticWeight": 0.3,
      "keywordWeight": 0.7
    },
    "filter": {
      "metadata": {
        "category": "errors",
        "database": "postgres",
        "status": "published"
      }
    }
  }'

Parameters

1. Required

   {
     query: string // Your search query
     namespaceId: string // Target namespace
   }
   

   CopyCopied!

2. Optional

   {
     topK?: number;          // Results to return (1-100, default: 10)
     scoreThreshold?: number; // Minimum score (0-1, default: 0)
     filter?: {              // Metadata filters
       metadata?: Record<string, any>;
     };
     searchType?: "SEMANTIC" | "HYBRID";  // Search type
     hybridConfig?: {        // Required for hybrid search
       semanticWeight: number;  // Range: 0-1
       keywordWeight: number;   // Range: 0-1
     };
   }
   

   CopyCopied!

Response Format

{
  "success": true,
  "message": "Search completed successfully",
  "data": {
    "results": [
      {
        "content": "string",     // Matched content
        "score": number,         // Similarity score (0-1)
        "metadata": {            // Document metadata
          "id": "string",        // Document ID
          "source": "string",    // Source file/URL
          "type": "string",      // Document type
          [key: string]: any     // Custom metadata
        }
      }
    ]
  }
}

Hybrid Search

Combine semantic and keyword search with weights:

{
  "searchType": "HYBRID",
  "hybridConfig": {
    "semanticWeight": 0.7, // Range: 0-1
    "keywordWeight": 0.3 // Range: 0-1
  }
}

Weight Guidelines

• Technical Content (0.3/0.7): Better for error messages and API docs
• Natural Language (0.8/0.2): Better for knowledge base and support articles
• Balanced (0.5/0.5): Good for mixed content types

Best Practices

Query Writing

1. Use natural language queries
2. Include relevant context
3. Be specific about what you're looking for

Metadata Strategy

Use a consistent schema:

{
  "metadata": {
    "type": "article|tutorial|reference",
    "category": "string",
    "tags": "string[]",
    "version": "semver",
    "status": "draft|published|archived",
    "lastUpdated": "ISO8601"
  }
}

Error Handling

Common error responses:

{
  "error": "INVALID_SEARCH_REQUEST",
  "message": "Query cannot be empty",
  "code": 400
}

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "code": 429,
  "details": {
    "retryAfter": 30
  }
}

For no results:

• Try broader queries
• Remove specific filters
• Check score threshold