Skip to main content
Performs semantic search across database tables using vector embeddings. This endpoint allows you to search for records based on meaning and context rather than exact keyword matches, making it perfect for finding conceptually similar content. 
POST https://api.worqhat.com/db/semantic-search

​
What Does This Endpoint Do?

This endpoint uses AI-powered vector embeddings to understand the semantic meaning of your search query and find records that are conceptually similar, even if they don’t contain the exact words you searched for. Think of it like having a smart assistant that understands what you’re looking for, not just the words you use. You’ll find this endpoint useful when you need to:
  • Find conceptually similar content: Search for products, articles, or documents that are related in meaning
  • Discover relevant information: Find records that match the intent of your query, not just keywords
  • Cross-table searches: Search across multiple tables simultaneously for comprehensive results
  • Handle synonyms and variations: Find results even when using different words to describe the same concept
  • Improve search relevance: Get more accurate results than traditional keyword-based search

​
How It Works

  1. You provide a natural language query describing what you’re looking for
  2. The API converts your query into a vector embedding that captures its semantic meaning
  3. The system searches for records with similar embeddings across your specified tables
  4. Results are returned with similarity scores showing how well each record matches your query

​
Code Examples

This example shows how to perform a simple semantic search on a single table.
  • 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 searchProducts() {
  try {
    // Call the semanticSearch method
    const response = await client.db.semanticSearch({
      query: "Find products related to machine learning",
      table: "products",
      limit: 10,
      threshold: 0.7,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Found ${response.results.length} relevant products`);
    console.log('Search results:', response.results);
    console.log('Query execution time:', response.executionTime, 'ms');
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error performing semantic search:', error.message);
  }
}

// Call the function
searchProducts();
This example shows how to search across multiple tables simultaneously.
  • 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 searchAcrossTables() {
  try {
    // Search across multiple tables
    const response = await client.db.semanticSearch({
      query: "artificial intelligence and automation",
      tables: ["products", "articles", "documents"],
      limit: 15,
      threshold: 0.6,
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Found ${response.results.length} relevant items across tables`);
    response.results.forEach(result => {
      console.log(`Table: ${result.table}, Similarity: ${result.similarity}`);
    });
    return response;
  } catch (error) {
    console.error('Error performing cross-table search:', error.message);
  }
}

searchAcrossTables();

​
Example 3: Semantic Search with Filters

This example shows how to combine semantic search with additional filters.
  • 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 searchWithFilters() {
  try {
    // Semantic search with additional filters
    const response = await client.db.semanticSearch({
      query: "premium electronics gadgets",
      table: "products",
      limit: 10,
      threshold: 0.7,
      filters: {
        category: "electronics",
        price: { min: 100, max: 500 },
        inStock: true
      },
      environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production
    });
    
    // Handle the successful response
    console.log(`Found ${response.results.length} filtered products`);
    console.log('Filtered results:', response.results);
    return response;
  } catch (error) {
    console.error('Error performing filtered search:', error.message);
  }
}

searchWithFilters();

​
Request Body Explained

​
query
string
required
The natural language search query describing what you’re looking for. Be descriptive and specific for better results.Examples: “Find products related to machine learning”, “Articles about sustainable energy”, “Documents on data privacy”
​
table
string
Single table to search in. Use this OR the tables parameter, not both.Example: “products”
​
tables
array
Multiple tables to search across. Use this OR the table parameter, not both.Example: [“products”, “articles”, “documents”]
​
limit
number
Maximum number of results to return. Range: 1-100, default: 10.
​
threshold
number
Minimum similarity score threshold (0-1). Only results above this threshold will be returned. Default: 0.7.
​
filters
object
Additional WHERE conditions to apply to narrow down results. Supports various filter types including ranges.Example: {"category": "electronics", "price": {"min": 100, "max": 500}}

​
Response Fields Explained

​
success
boolean
true if the search was successful, false otherwise.
​
results
array
Array of search results, each containing:
  • table: The table where the record was found
  • record: The actual record data
  • similarity: Similarity score (0-1) indicating how well the record matches your query
  • _meta: Additional metadata including matched fields
​
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": [
    {
      "table": "products",
      "record": {
        "id": "prod_123",
        "name": "AI-Powered Smart Assistant",
        "description": "Advanced machine learning device for home automation",
        "category": "electronics",
        "price": 299.99
      },
      "similarity": 0.847,
      "_meta": {
        "matched_fields": ["name", "description"]
      }
    },
    {
      "table": "products",
      "record": {
        "id": "prod_456",
        "name": "Neural Network Processor",
        "description": "High-performance computing unit for AI applications",
        "category": "electronics",
        "price": 599.99
      },
      "similarity": 0.823,
      "_meta": {
        "matched_fields": ["description"]
      }
    }
  ],
  "query_embedding_preview": [0.123, -0.456, 0.789, -0.321, 0.654],
  "executionTime": 245
}

​
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
”Query too short”The search query is too briefUse more descriptive queries with at least 3-5 words
”Threshold too high”No results meet the similarity thresholdLower the threshold value (try 0.5-0.6)
“Unauthorized”Invalid or missing API keyCheck that you’re using a valid API key

​
Tips for Better Results

  • Use descriptive queries: Include context and details about what you’re looking for
  • Experiment with thresholds: Start with 0.7 and adjust based on your needs
  • Combine with filters: Use filters to narrow down results after semantic matching
  • Try different phrasings: If results aren’t relevant, rephrase your query
  • Use cross-table search: Search multiple tables for comprehensive results
  • Review similarity scores: Higher scores indicate better matches

​
Best Practices

  • Start broad, then narrow: Begin with general queries and add filters as needed
  • Monitor performance: Use execution time to optimize your queries
  • Combine with traditional search: Use semantic search alongside keyword search for best results
  • Regular updates: Re-index your data when content changes significantly
  • Test different queries: Experiment with various phrasings to find what works best for your data