Text to SQL

Convert natural language to SQL queries for various database types.

POST /v1/ai/sql

Javascript

import { JigsawStack } from "jigsawstack";

const jigsaw = JigsawStack({ apiKey: "your-api-key" });

const response = await jigsaw.text_to_sql({
  "database": "postgresql",
  "prompt": "Find all transactions with amounts exceeding $10,000, sorted by transaction date",
  "sql_schema": "\n            CREATE TABLE Transactions (\n              transaction_id INT PRIMARY KEY, \n              user_id INT NOT NULL,\n              total_amount DECIMAL(10, 2) NOT NULL, \n              transaction_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n              status VARCHAR(20) DEFAULT 'pending',\n              FOREIGN KEY(user_id) REFERENCES Users(user_id)\n            )\n          "
})

Response

{
  "success": true,
  "sql": "SELECT * FROM Transactions WHERE total_amount > 10000 ORDER BY transaction_date;",
  "_usage": {
        "input_tokens": 132,
        "output_tokens": 27,
        "inference_time_tokens": 877,
        "total_tokens": 1036
  }
}

Request Parameters

Body

prompt · string · required

The natural language prompt that will be translated to an SQL query. Minimum length: 10 characters

sql_schema · string

The database schema where the query will be run. Not required if file_store_key is specified.

database · enum

The database type to generate SQL for. Specifying this parameter improves SQL generation accuracy by applying database-specific syntax and optimizations.

• postgresql - PostgreSQL database
• mysql - MySQL database
• sqlite - SQLite database

file_store_key · string

The key used to store the database schema on Jigsawstack file Storage. Not required if sql_schema is specified.

Either file_store_key or sql_schema can be provided not both.

Header

x-api-key · string · required

Your JigsawStack API key

Response Structure

success · boolean

Indicates whether the call was successful.

_usage · object

Usage information for the API call.

Show _usage

input_tokens · number

Number of input tokens processed.

output_tokens · number

Number of output tokens generated.

inference_time_tokens · number

Number of tokens processed during inference time.

total_tokens · number

Total number of tokens used (input + output).

log_id · string

A unique identifier for the request

sql · string

The generated SQL query based on the natural language prompt and provided schema.

Javascript

import { JigsawStack } from "jigsawstack";

const jigsaw = JigsawStack({ apiKey: "your-api-key" });

const response = await jigsaw.text_to_sql({
  "database": "postgresql",
  "prompt": "Find all transactions with amounts exceeding $10,000, sorted by transaction date",
  "sql_schema": "\n            CREATE TABLE Transactions (\n              transaction_id INT PRIMARY KEY, \n              user_id INT NOT NULL,\n              total_amount DECIMAL(10, 2) NOT NULL, \n              transaction_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n              status VARCHAR(20) DEFAULT 'pending',\n              FOREIGN KEY(user_id) REFERENCES Users(user_id)\n            )\n          "
})

Response

{
  "success": true,
  "sql": "SELECT * FROM Transactions WHERE total_amount > 10000 ORDER BY transaction_date;",
  "_usage": {
        "input_tokens": 132,
        "output_tokens": 27,
        "inference_time_tokens": 877,
        "total_tokens": 1036
  }
}