VecTrail RAG Search API - Documentation

📖 Overview

The VecTrail RAG Search API provides powerful, flexible search capabilities across your vectorized database tables using natural language queries. Combine the precision of vector similarity search with the intelligence of AI-enhanced query processing.

🎯 Perfect for: Building intelligent search experiences, chatbots, content discovery systems, and AI-powered applications that need to understand and search your data contextually.

✨ Key Features

🔍 Multi-Table Search

Search across multiple database tables simultaneously with a single query

🤖 AI Query Enhancement AI

OpenAI automatically improves queries with synonyms and context-aware terms

🛡️ Privacy Controls

Hide sensitive fields like emails, phones, IDs from search results

📅 Date Filtering

Filter results by date ranges using any timestamp column in your data

⚡ Vector Speed

Lightning-fast semantic search using state-of-the-art vector databases

📊 Structured Output

Clean, standardized JSON responses with relevance scores and metadata

🌐 API Endpoints

Main Search Endpoint

POST /api/rag-search/connections/:connectionId/search

Perform intelligent RAG searches across your vectorized tables.

Helper Endpoint

GET /api/rag-search/connections/:connectionId/tables

Get available tables and their schema information for a connection.

📋 Request Parameters

Parameter	Type	Required	Default	Description
`tables`	string[]	Required	-	Array of table names to search in
`query`	string	Required	-	Natural language search query
`hiddenFields`	string[]	Optional	[]	Fields to exclude from results (e.g., email, phone)
`dateRange`	object	Optional	-	Date range filter with from, to, and column
`limit`	number	Optional	10	Maximum number of results to return
`threshold`	number	Optional	0.7	Similarity threshold (0-1)
`enhanceQuery`	boolean	Optional	true	Use OpenAI to enhance the query
`includeMetadata`	boolean	Optional	false	Include vector metadata in response

💡 Request Examples

Basic Search

cURL Request

curl -X POST "https://your-api.com/api/rag-search/connections/your-connection-id/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "tables": ["mentors"],
    "query": "experienced JavaScript developer"
  }'

Advanced Search with Filtering

JavaScript/Node.js

const response = await fetch('/api/rag-search/connections/your-connection-id/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    tables: ['mentors', 'mentor_education'],
    query: 'machine learning expert with PhD',
    hiddenFields: ['email', 'phone', 'personal_id'],
    dateRange: {
      from: '2024-01-01',
      to: '2025-12-31',
      column: 'last_updated'
    },
    limit: 20,
    threshold: 0.8,
    enhanceQuery: true
  })
});

const data = await response.json();

Python Example

Python

import requests

url = "https://your-api.com/api/rag-search/connections/your-connection-id/search"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_JWT_TOKEN"
}

payload = {
    "tables": ["mentors"],
    "query": "experienced data scientist",
    "hiddenFields": ["email", "phone"],
    "limit": 15,
    "enhanceQuery": True
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

📊 Response Format

JSON Response

{
  "success": true,
  "query": {
    "original": "experienced JavaScript developer",
    "enhanced": "experienced JavaScript developer React Node.js frontend backend programming",
    "embedding_tokens": 18
  },
  "filters": {
    "tables": ["mentors"],
    "hiddenFields": ["email", "phone"],
    "dateRange": {
      "from": "2024-01-01",
      "to": "2025-12-31",
      "column": "last_updated"
    }
  },
  "results": [
    {
      "table": "mentors",
      "score": 0.89,
      "data": {
        "name": "John Smith",
        "skills": "JavaScript, React, Node.js, Python",
        "experience_years": 8,
        "bio": "Senior full-stack developer with expertise in modern web technologies..."
      }
    }
  ],
  "summary": {
    "totalResults": 5,
    "searchTime": 245,
    "tablesSearched": ["mentors"]
  }
}

💡 Pro Tip: The score field indicates relevance (0-1), with higher scores meaning better matches. Use this to rank and filter results in your application.

🎯 Use Cases & Applications

🤝 HR & Recruitment

"Find candidates with Python and machine learning experience in the last 6 months"

📞 Customer Support

"Find customers with billing issues reported in the last 30 days"

📚 Content Discovery

"Find articles about renewable energy published this year"

📦 Inventory Management

"Find products with low stock levels under $50"

🔬 Research & Analytics

"Find research papers on AI ethics from 2024"

🤖 Chatbots & AI

Power intelligent conversational interfaces with contextual data retrieval

🚀 Try It Now

Interactive API Demo

Test the RAG Search API with your own queries:

⚠️ Note: This demo requires a valid JWT token and connection ID. Replace the placeholder values with your actual credentials.

🔐 Authentication & Security

JWT Token Authentication

All requests require a valid JWT token in the Authorization header:

Authorization Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Security Features

User Isolation: Users can only search their own database connections
Field Filtering: Automatically exclude sensitive data from responses
Input Validation: All parameters are validated and sanitized
Rate Limiting: Built-in protection against API abuse

💰 Token Usage & Costs

📊 Token Breakdown: The API uses OpenAI tokens for query enhancement and embedding generation. Typical usage ranges from 10-50 tokens per search request.

Cost Optimization Tips

Set enhanceQuery: false to disable OpenAI query enhancement and save tokens
Use appropriate threshold values to get relevant results without over-searching
Limit search scope with specific table selection rather than searching all tables
Cache frequent queries on your application side to reduce API calls