WorqHat Documentation

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.

You can use both named parameters ({param}) and positional parameters ($1, $2) to safely pass values into your queries, preventing SQL injection attacks.

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

You provide a SQL query to execute (with optional parameters)
You can use named parameters ({param}) or positional parameters ($1, $2) for safe value substitution
The API runs your query against the database with security guardrails
The results are returned as an array of objects

Code Examples

Example 1: Basic SQL Query with Named Parameters

This example shows how to execute a simple SQL query using named parameters to safely pass values.

execute-query.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 fetchActiveUsers() {try {  // Call the executeQuery method with named parameters  const response = await client.db.executeQuery({    query: "SELECT * FROM users WHERE status = {status} LIMIT {limit}",    params: {      status: "active",      limit: 10    },    environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production  });    // 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 functionfetchActiveUsers();

Example 2: Advanced SQL Query with Positional Parameters

This example shows how to execute a more complex SQL query using positional parameters for safe value substitution.

execute-query-positional.js

import Worqhat from 'worqhat';// Initialize the client with your API keyconst client = new Worqhat({apiKey: process.env.WORQHAT_API_KEY,});async function generateSalesReport() {try {  // Complex SQL query with positional parameters  const query = `    SELECT       category,       COUNT(*) as order_count,       SUM(quantity) as total_items,       SUM(price * quantity) as total_revenue    FROM orders    WHERE order_date >= $1    GROUP BY category    ORDER BY total_revenue DESC  `;    // Execute the query with positional parameters  const response = await client.db.executeQuery({     query,    params: ['2025-01-01'],    environment: process.env.WORQHAT_ENVIRONMENT || 'production' // Defaults to production  });    // 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();

Example 3: Mixed Parameter Types

This example shows how to use both named and positional parameters in the same query for maximum flexibility.

execute-query-mixed.js

import Worqhat from 'worqhat';// Initialize the client with your API keyconst client = new Worqhat({apiKey: process.env.WORQHAT_API_KEY,});async function searchUsers() {try {  // Query using both parameter types  const response = await client.db.executeQuery({    query: "SELECT * FROM users WHERE status = {status} AND created_at >= $1 ORDER BY {sort_by} LIMIT $2",    params: {      status: "active",      sort_by: "created_at"    },    environment: process.env.WORQHAT_ENVIRONMENT || 'production', // Defaults to production    // Note: Positional parameters are passed as an array    // The query will use $1 and $2 for the positional params  });    console.log('Search completed successfully');  console.log('Results:', response.data);  return response;} catch (error) {  console.error('Error searching users:', error.message);}}searchUsers();

Request Body Explained

querystringbodyrequired

The SQL query to execute against the database. This can be any valid SQL query that reads data (SELECT statements).

You can use either:

Named parameters: {param} syntax (e.g., SELECT * FROM users WHERE status = {status})
Positional parameters: $1, $2, $3 syntax (e.g., SELECT * FROM users WHERE status = $1)

For security reasons, certain operations may be restricted to prevent accidental data loss or unauthorized access.

paramsobject | arraybodyoptional

Parameters to safely substitute into your SQL query. Choose one format:

For named parameters ({param} syntax): Provide an object with key-value pairs.

named-params.json

{"status": "active", "limit": 10}

For positional parameters ($1, $2 syntax): Provide an array of values in order.

positional-params.json

["active", 10]

environmentstringbodyoptional

The environment to query (development, staging, production). Defaults to production if not specified.

Options: development, staging, production

Response Fields Explained

successbooleanrequired

true if the query was executed successfully, false otherwise.

dataarrayrequired

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.

querystringrequired

The SQL query that was executed. This is useful for debugging and audit purposes.

executionTimeintegerrequired

The time taken to execute the query in milliseconds. This can help you optimize slow queries.

Example Response

response.json

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

Error	Cause	Solution
"Table not found"	The specified table doesn't exist	Check your table name for typos
"Syntax error in SQL query"	The SQL query contains syntax errors	Review your SQL syntax and fix any errors
"Operation not allowed"	You're trying to perform a restricted operation	Use only allowed operations (typically SELECT statements)
"Query timeout"	The query took too long to execute	Optimize your query or add more specific conditions
"Unauthorized"	Invalid or missing API key	Check that you're using a valid API key

Tips for Successful Queries

Use parameters for all dynamic values to prevent SQL injection attacks
Choose the right parameter type: Use named parameters for readability, positional for performance
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

Parameter Safety

Both named ({param}) and positional ($1, $2) parameters provide protection against SQL injection by properly escaping values. Choose the approach that best fits your use case:

Named parameters: More readable and maintainable for complex queries
Positional parameters: Slightly more performant for simple queries with few parameters
Mixed usage: You can use both types in the same query for maximum flexibility