Initialize the client with your API key

Executes database queries using natural language. This endpoint translates natural language questions into SQL and executes them against WorqDB.

POST https://api.worqhat.com/db/nl-query

What Does This Endpoint Do?

This endpoint allows you to query your database using plain English questions instead of writing SQL. Think of it like having a conversation with your database - you ask questions in natural language, and the API translates them into SQL queries and returns the results.

When to Use Natural Language Queries

• For non-technical users who need to query data but don't know SQL
• For quick data exploration without writing complex SQL queries
• For building conversational interfaces that need to translate user questions into database queries
• For prototyping when you want to quickly test ideas without writing formal queries

How It Works

1. You provide a natural language question about your data
2. The API translates your question into a SQL query
3. The SQL query is executed against your database
4. The results are returned along with the generated SQL for transparency

Request Body

Response

Code Examples

Example: Basic Natural Language Query

This example shows how to execute a simple natural language query to retrieve active user count.

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 countActiveUsers() {try {  // Call the processNlQuery method  const response = await client.db.processNlQuery({    question: "How many active users do we have?",    environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production  });    // Handle the successful response  console.log(`Result: ${JSON.stringify(response.data)}`);  console.log('Generated SQL:', response.sql);  console.log('Query execution time:', response.executionTime, 'ms');  return response;} catch (error) {  // Handle any errors  console.error('Error executing query:', error.message);}}// Call the functioncountActiveUsers();

Example: Advanced Natural Language Query

This example shows how to execute a more complex natural language query to analyze sales data.

import Worqhat from 'worqhat';// Initialize the client with your API keyconst client = new Worqhat({apiKey: process.env.WORQHAT_API_KEY,environment: process.env.WORQHAT_ENVIRONMENT || 'production', // Defaults to production});async function analyzeSalesData() {try {  // More complex natural language query  const response = await client.db.processNlQuery({    question: "What were the top 3 product categories by revenue last quarter?",    environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production  });    // Handle the successful response  console.log('Analysis results:', response.data);  console.log('Generated SQL:', response.sql);  return response;} catch (error) {  console.error('Error analyzing sales data:', error.message);}}analyzeSalesData();

Request Body Explained

Response Fields Explained

Example Response

{"success": true,"data": [  {    "count": 157  }],"sql": "SELECT COUNT(*) as count FROM users WHERE status = 'active'","executionTime": 38,"message": "Query processed successfully"}

Common Errors and How to Fix Them

Tips for Better Results

• Be specific: Include relevant details like time periods, categories, or conditions
• Keep it simple: Start with straightforward questions and gradually increase complexity
• Use common terms: Use terms that match your database schema when possible
• Review the generated SQL: Check the returned SQL to understand how your question was interpreted

Example Questions

Here are some examples of natural language questions you can ask:

• "How many users signed up last week?"
• "What's the average order value for premium customers?"
• "Show me the top 5 products by sales"
• "Count active users by country"
• "What was the total revenue in March 2025?"