Skip to main content
Combines semantic search using vector embeddings with traditional keyword search. This endpoint provides weighted scoring between semantic similarity and keyword matching, giving you the best of both worlds for comprehensive search results. 
POST https://api.worqhat.com/db/hybrid-search

​
What Does This Endpoint Do?

This endpoint intelligently combines two powerful search methods:
  • Semantic search: Understands the meaning and context of your query
  • Keyword search: Finds exact matches for specific terms
By blending these approaches with configurable weights, you get more comprehensive and accurate search results that capture both conceptual relevance and precise term matching. You’ll find this endpoint useful when you need to:
  • Balance precision and recall: Get both exact matches and conceptually similar results
  • Handle technical queries: Find documents containing specific terms while understanding context
  • Improve search quality: Combine the strengths of both semantic and keyword search
  • Handle mixed queries: Search queries that contain both natural language and specific keywords
  • Optimize for your use case: Adjust weights based on whether you prioritize semantic understanding or exact matching

​
How It Works

  1. You provide a search query that can contain both natural language and keywords
  2. The system performs semantic analysis using vector embeddings
  3. Simultaneously, it performs keyword matching on specified text columns
  4. Results are scored using configurable weights for semantic vs keyword relevance
  5. A combined score ranks results by overall relevance

​
Code Examples

This example shows how to perform a hybrid search with default weights.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY, // Always use environment variables for API keys
});

async function hybridSearch() {
  try {
    // Call the hybridSearch method
    const response = await client.db.hybridSearch({
      query: "machine learning algorithms neural networks",
      table: "products",
      limit: 10,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Found ${response.results.length} relevant products`);
    response.results.forEach(result => {
      console.log(`Combined Score: ${result.combined_score}, Semantic: ${result.semantic_score}, Keyword: ${result.keyword_score}`);
    });
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error performing hybrid search:', error.message);
  }
}

// Call the function
hybridSearch();

​
Example 2: Custom Weight Configuration

This example shows how to adjust the weights for semantic vs keyword scoring.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function customWeightSearch() {
  try {
    // Hybrid search with custom weights (prioritize semantic understanding)
    const response = await client.db.hybridSearch({
      query: "AI-powered automation solutions",
      table: "products",
      semantic_weight: 0.8,  // Higher weight for semantic understanding
      keyword_weight: 0.2,   // Lower weight for exact keyword matching
      limit: 10,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Found ${response.results.length} products with semantic focus`);
    console.log('Results:', response.results);
    return response;
  } catch (error) {
    console.error('Error performing custom weight search:', error.message);
  }
}

customWeightSearch();

​
Example 3: Custom Text Columns

This example shows how to specify which columns to include in keyword search.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function customColumnsSearch() {
  try {
    // Hybrid search with custom text columns
    const response = await client.db.hybridSearch({
      query: "sustainable energy renewable power",
      table: "articles",
      text_columns: ["title", "summary", "tags"], // Only search these columns for keywords
      semantic_weight: 0.6,
      keyword_weight: 0.4,
      limit: 15,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Found ${response.results.length} articles`);
    console.log('Search results:', response.results);
    return response;
  } catch (error) {
    console.error('Error performing custom columns search:', error.message);
  }
}

customColumnsSearch();

​
Request Body Explained

​
query
string
required
Search query combining natural language and keywords. Can include both conceptual descriptions and specific terms.Examples: “machine learning algorithms neural networks”, “AI-powered automation solutions”, “sustainable energy renewable power”
​
table
string
required
Table to search in.Example: “products”
​
text_columns
array
Columns to include in keyword search. Defaults to [“description”, “content”, “title”, “name”] if not specified.Example: [“title”, “description”, “tags”]
​
semantic_weight
number
Weight for semantic similarity score (0-1). Default: 0.7. Higher values prioritize semantic understanding over exact keyword matching.
​
keyword_weight
number
Weight for keyword matching score (0-1). Default: 0.3. Higher values prioritize exact term matching over semantic understanding.
​
limit
number
Maximum number of results to return. Range: 1-100, default: 10.

​
Response Fields Explained

​
success
boolean
true if the search was successful, false otherwise.
​
results
array
Array of search results, each containing:
  • record: The actual record data
  • combined_score: Overall relevance score combining semantic and keyword scores
  • semantic_score: Semantic similarity score (0-1)
  • keyword_score: Keyword matching score (0-1)
  • _meta: Additional metadata including search type and weights used
​
query_embedding_preview
array
First 5 dimensions of the query embedding vector for debugging purposes.
​
executionTime
number
Search execution time in milliseconds.

​
Example Response

{
  "success": true,
  "results": [
    {
      "record": {
        "id": "prod_123",
        "name": "AI-Powered Smart Assistant",
        "description": "Advanced machine learning device for home automation",
        "category": "electronics",
        "price": 299.99
      },
      "combined_score": 0.823,
      "semantic_score": 0.756,
      "keyword_score": 0.234,
      "_meta": {
        "search_type": "hybrid",
        "weights": {
          "semantic": 0.7,
          "keyword": 0.3
        }
      }
    },
    {
      "record": {
        "id": "prod_456",
        "name": "Neural Network Processor",
        "description": "High-performance computing unit for AI applications",
        "category": "electronics",
        "price": 599.99
      },
      "combined_score": 0.789,
      "semantic_score": 0.712,
      "keyword_score": 0.198,
      "_meta": {
        "search_type": "hybrid",
        "weights": {
          "semantic": 0.7,
          "keyword": 0.3
        }
      }
    }
  ],
  "query_embedding_preview": [0.123, -0.456, 0.789, -0.321, 0.654],
  "executionTime": 312
}

​
Common Errors and How to Fix Them

ErrorCauseSolution
”Table not found”The specified table doesn’t existCheck your table name for typos
”No embeddings found”The table doesn’t have vector embeddingsEnsure your table has been processed for embeddings
”Invalid weight values”Semantic and keyword weights don’t sum to 1.0Ensure weights sum to 1.0 (e.g., 0.7 + 0.3 = 1.0)
“Text columns not found”Specified columns don’t exist in the tableCheck column names and ensure they exist
”Query too short”The search query is too briefUse more descriptive queries with at least 3-5 words
”Unauthorized”Invalid or missing API keyCheck that you’re using a valid API key

​
Tips for Better Results

  • Balance your weights: Start with default 0.7/0.3 ratio and adjust based on your needs
  • Use descriptive queries: Include both conceptual terms and specific keywords
  • Choose relevant text columns: Select columns that contain searchable content
  • Experiment with weights:
    • Higher semantic weight (0.8-0.9) for conceptual searches
    • Higher keyword weight (0.6-0.8) for exact term matching
  • Monitor scores: Review individual semantic and keyword scores to understand result quality
  • Combine with filters: Use additional WHERE conditions to narrow results after hybrid scoring

​
Weight Configuration Guidelines

​
Semantic-Focused (0.8 semantic, 0.2 keyword)

  • Use when you want to find conceptually similar content
  • Good for discovery and exploration
  • Handles synonyms and related concepts well

​
Balanced (0.7 semantic, 0.3 keyword)

  • Default configuration for most use cases
  • Provides good balance between precision and recall
  • Works well for general-purpose search

​
Keyword-Focused (0.4 semantic, 0.6 keyword)

  • Use when exact term matching is important
  • Good for technical documentation and specifications
  • Prioritizes precision over conceptual understanding

​
Equal Weight (0.5 semantic, 0.5 keyword)

  • Use when you’re unsure which approach works better
  • Good starting point for experimentation
  • Provides equal consideration to both methods