Executes a raw SQL query directly against WorqDB. This endpoint provides direct SQL access with security guardrails to prevent destructive operations. 
POST https://api.worqhat.com/db/query

​
What Does This Endpoint Do?

This endpoint allows you to execute SQL queries directly against your database. Think of it like having direct access to your database through SQL, but with safety measures in place to prevent accidental data loss or destructive operations.

​
When to Use SQL Queries

You’ll find this endpoint useful when you need to:
  • Run complex queries: Perform advanced data analysis with SQL
  • Generate reports: Create custom reports with aggregations and calculations
  • Fetch specific data: Retrieve exactly what you need with precise SQL queries
  • Run analytical queries: Perform calculations and aggregations on your data
  • Use SQL functions: Leverage SQL’s built-in functions for data manipulation
  • Perform bulk operations: Execute operations on multiple records efficiently

​
How It Works

  1. You provide a SQL query to execute
  2. The API runs your query against the database with security guardrails
  3. The results are returned as an array of objects

​
Code Examples

​
Example: Basic SQL Query

This example shows how to execute a simple SQL query to retrieve active users. 
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 fetchActiveUsers() {
  try {
    // Call the executeQuery method
    const response = await client.db.executeQuery({
      query: "SELECT * FROM users WHERE status = 'active' LIMIT 10"
    });
    
    // Handle the successful response
    console.log(`Found ${response.data.length} active users`);
    console.log('Query execution time:', response.executionTime, 'ms');
    console.log('Results:', response.data);
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error executing query:', error.message);
  }
}

// Call the function
fetchActiveUsers();

​
Example: Advanced SQL Query

This example shows how to execute a more complex SQL query with aggregations. 
import Worqhat from 'worqhat';

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

async function generateSalesReport() {
  try {
    // Complex SQL query with aggregations
    const query = `
      SELECT 
        category, 
        COUNT(*) as order_count, 
        SUM(quantity) as total_items, 
        SUM(price * quantity) as total_revenue
      FROM orders
      WHERE order_date >= '2025-01-01'
      GROUP BY category
      ORDER BY total_revenue DESC
    `;
    
    // Execute the query
    const response = await client.db.executeQuery({ query });
    
    // Handle the successful response
    console.log('Sales report generated successfully');
    console.log('Report data:', response.data);
    return response;
  } catch (error) {
    console.error('Error generating sales report:', error.message);
  }
}

generateSalesReport();

​
Request Body Explained

​
query
string
required
The SQL query to execute against the database. This can be any valid SQL query that reads data (SELECT statements).For security reasons, certain operations may be restricted to prevent accidental data loss or unauthorized access.

​
Response Fields Explained

​
success
boolean
true if the query was executed successfully, false otherwise.
​
data
array
An array of objects containing the query results. Each object represents a row in the result set, with properties corresponding to the columns in your query.
​
query
string
The SQL query that was executed. This is useful for debugging and audit purposes.
​
executionTime
integer
The time taken to execute the query in milliseconds. This can help you optimize slow queries.

​
Example Response

{
  "success": true,
  "data": [
    {
      "id": "user_123",
      "name": "John Doe",
      "email": "john@example.com",
      "status": "active"
    },
    {
      "id": "user_456",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "status": "active"
    }
  ],
  "query": "SELECT * FROM users WHERE status = 'active' LIMIT 10",
  "executionTime": 42
}

​
Common Errors and How to Fix Them

ErrorCauseSolution
”Table not found”The specified table doesn’t existCheck your table name for typos
”Syntax error in SQL query”The SQL query contains syntax errorsReview your SQL syntax and fix any errors
”Operation not allowed”You’re trying to perform a restricted operationUse only allowed operations (typically SELECT statements)
“Query timeout”The query took too long to executeOptimize your query or add more specific conditions
”Unauthorized”Invalid or missing API keyCheck that you’re using a valid API key

​
Tips for Successful Queries

  • Use LIMIT clauses to restrict the number of results returned
  • Be specific with your SELECT columns rather than using SELECT *
  • Add appropriate WHERE clauses to filter results
  • Use indexes when querying large tables
  • Test complex queries on small datasets first
  • Consider query performance for production applications