Initialize the client with your API key
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.
When to Use Semantic Search
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
- You provide a natural language query describing what you're looking for
- The API converts your query into a vector embedding that captures its semantic meaning
- The system searches for records with similar embeddings across your specified tables
- Results are returned with similarity scores showing how well each record matches your query
Code Examples
Example 1: Basic Semantic Search
This example shows how to perform a simple semantic search on a single table.
semantic-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 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 functionsearchProducts();Example 2: Cross-Table Semantic Search
This example shows how to search across multiple tables simultaneously.
semantic-search-cross-table.js
import Worqhat from 'worqhat';// Initialize the client with your API keyconst 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.
semantic-search-filters.js
import Worqhat from 'worqhat';// Initialize the client with your API keyconst 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
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"
Single table to search in. Use this OR the tables parameter, not both.
Example: "products"
Multiple tables to search across. Use this OR the table parameter, not both.
Example: ["products", "articles", "documents"]
Maximum number of results to return. Range: 1-100, default: 10.
Minimum similarity score threshold (0-1). Only results above this threshold will be returned. Default: 0.7.
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
true if the search was successful, false otherwise.
Array of search results, each containing:
table: The table where the record was foundrecord: The actual record datasimilarity: Similarity score (0-1) indicating how well the record matches your query_meta: Additional metadata including matched fields
First 5 dimensions of the query embedding vector for debugging purposes.
Search execution time in milliseconds.
Example Response
response.json
{"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
| 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 |
| "Query too short" | The search query is too brief | Use more descriptive queries with at least 3-5 words |
| "Threshold too high" | No results meet the similarity threshold | Lower the threshold value (try 0.5-0.6) |
| "Unauthorized" | Invalid or missing API key | Check 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