WorqHat Documentation

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.

When to Use Hybrid Search

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

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

Code Examples

Example 1: Basic Hybrid Search

This example shows how to perform a hybrid search with default weights.

hybrid-search.js

import Worqhat from 'worqhat';// Initialize the client with your API keyconst 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 functionhybridSearch();

Example 2: Custom Weight Configuration

This example shows how to adjust the weights for semantic vs keyword scoring.

hybrid-search-custom-weights.js

import Worqhat from 'worqhat';// Initialize the client with your API keyconst 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.

hybrid-search-custom-columns.js

import Worqhat from 'worqhat';// Initialize the client with your API keyconst 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

querystringbodyrequired

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"

tablestringbodyrequired

Table to search in.

Example: "products"

text_columnsarraybodyoptional

Columns to include in keyword search. Defaults to ["description", "content", "title", "name"] if not specified.

Example: ["title", "description", "tags"]

semantic_weightnumberbodyoptional

Weight for semantic similarity score (0-1). Default: 0.7. Higher values prioritize semantic understanding over exact keyword matching.

keyword_weightnumberbodyoptional

Weight for keyword matching score (0-1). Default: 0.3. Higher values prioritize exact term matching over semantic understanding.

limitnumberbodyoptional

Maximum number of results to return. Range: 1-100, default: 10.

Response Fields Explained

successbooleanrequired

true if the search was successful, false otherwise.

resultsarrayrequired

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_previewarrayrequired

First 5 dimensions of the query embedding vector for debugging purposes.

executionTimenumberrequired

Search execution time in milliseconds.

Example Response

response.json

{"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

Error	Cause	Solution
"Table not found"	The specified table doesn't exist	Check your table name for typos
"No embeddings found"	The table doesn't have vector embeddings	Ensure your table has been processed for embeddings
"Invalid weight values"	Semantic and keyword weights don't sum to 1.0	Ensure weights sum to 1.0 (e.g., 0.7 + 0.3 = 1.0)
"Text columns not found"	Specified columns don't exist in the table	Check column names and ensure they exist
"Query too short"	The search query is too brief	Use more descriptive queries with at least 3-5 words
"Unauthorized"	Invalid or missing API key	Check 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