Skip to main content
POST
/
v1
/
ai
/
sql
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          "
})
from jigsawstack import JigsawStack

jigsaw = JigsawStack(api_key="your-api-key")

response = 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          "
})
curl https://api.jigsawstack.com/v1/ai/sql \
-X POST \
-H 'Content-Type: application/json' \
-H 'x-api-key: your-api-key' \
-d '{"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          "}'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.jigsawstack.com/v1/ai/sql');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'x-api-key: your-api-key',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"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');

$response = curl_exec($ch);

curl_close($ch);

require 'net/http'

uri = URI('https://api.jigsawstack.com/v1/ai/sql')
req = Net::HTTP::Post.new(uri)
req.content_type = 'application/json'
req['x-api-key'] = 'your-api-key'

req.body = '{"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'

req_options = {
use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(req)
end

package main

import (
"fmt"
"io"
"log"
"net/http"
"strings"
)

func main() {
client := &http.Client{}
var data = strings.NewReader(`{"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`)
req, err := http.NewRequest("POST", "https://api.jigsawstack.com/v1/ai/sql", data)
if err != nil {
	log.Fatal(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "your-api-key")
resp, err := client.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
bodyText, err := io.ReadAll(resp.Body)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)
}

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.jigsawstack.com/v1/ai/sql"))
.POST(BodyPublishers.ofString("{\"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"))
.setHeader("Content-Type", "application/json")
.setHeader("x-api-key", "your-api-key")
.build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

import Foundation

let url = URL(string: "https://api.jigsawstack.com/v1/ai/sql")!
let headers = [
"Content-Type": "application/json",
"x-api-key": "your-api-key"
]

var request = URLRequest(url: url)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = "{\"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".data(using: .utf8)

let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
    print(error)
} else if let data = data {
    let str = String(data: data, encoding: .utf8)
    print(str ?? "")
}
}

task.resume()

import 'package:http/http.dart' as http;

void main() async {
final headers = {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
};

final data = '{"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';

final url = Uri.parse('https://api.jigsawstack.com/v1/ai/sql');

final res = await http.post(url, headers: headers, body: data);
final status = res.statusCode;
if (status != 200) throw Exception('http.post error: statusCode= $status');

print(res.body);
}

import java.io.IOException
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

val MEDIA_TYPE = "application/json".toMediaType()

val requestBody = "{\"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"

val request = Request.Builder()
.url("https://api.jigsawstack.com/v1/ai/sql")
.post(requestBody.toRequestBody(MEDIA_TYPE))
.header("Content-Type", "application/json")
.header("x-api-key", "your-api-key")
.build()

client.newCall(request).execute().use { response ->
if (!response.isSuccessful) throw IOException("Unexpected code $response")
response.body!!.string()
}

using System.Net.Http.Headers;
using System.Net.Http.Json;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.jigsawstack.com/v1/ai/sql");
request.Headers.Add("x-api-key", "your-api-key");
request.Content = JsonContent.Create(new
{
database = "postgresql",
prompt = "Find all transactions with amounts exceeding $10,000, sorted by transaction date",
sql_schema = "
        CREATE TABLE Transactions (
          transaction_id INT PRIMARY KEY, 
          user_id INT NOT NULL,
          total_amount DECIMAL(10, 2) NOT NULL, 
          transaction_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
          status VARCHAR(20) DEFAULT 'pending',
          FOREIGN KEY(user_id) REFERENCES Users(user_id)
        )
      "
});
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

Console.WriteLine(responseBody);
{
  "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.
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.
log_id
string
A unique identifier for the request
sql
string
The generated SQL query based on the natural language prompt and provided schema.
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          "
})
from jigsawstack import JigsawStack

jigsaw = JigsawStack(api_key="your-api-key")

response = 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          "
})
curl https://api.jigsawstack.com/v1/ai/sql \
-X POST \
-H 'Content-Type: application/json' \
-H 'x-api-key: your-api-key' \
-d '{"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          "}'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.jigsawstack.com/v1/ai/sql');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'x-api-key: your-api-key',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"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');

$response = curl_exec($ch);

curl_close($ch);

require 'net/http'

uri = URI('https://api.jigsawstack.com/v1/ai/sql')
req = Net::HTTP::Post.new(uri)
req.content_type = 'application/json'
req['x-api-key'] = 'your-api-key'

req.body = '{"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'

req_options = {
use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(req)
end

package main

import (
"fmt"
"io"
"log"
"net/http"
"strings"
)

func main() {
client := &http.Client{}
var data = strings.NewReader(`{"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`)
req, err := http.NewRequest("POST", "https://api.jigsawstack.com/v1/ai/sql", data)
if err != nil {
	log.Fatal(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "your-api-key")
resp, err := client.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
bodyText, err := io.ReadAll(resp.Body)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)
}

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.jigsawstack.com/v1/ai/sql"))
.POST(BodyPublishers.ofString("{\"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"))
.setHeader("Content-Type", "application/json")
.setHeader("x-api-key", "your-api-key")
.build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

import Foundation

let url = URL(string: "https://api.jigsawstack.com/v1/ai/sql")!
let headers = [
"Content-Type": "application/json",
"x-api-key": "your-api-key"
]

var request = URLRequest(url: url)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = "{\"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".data(using: .utf8)

let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
    print(error)
} else if let data = data {
    let str = String(data: data, encoding: .utf8)
    print(str ?? "")
}
}

task.resume()

import 'package:http/http.dart' as http;

void main() async {
final headers = {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
};

final data = '{"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';

final url = Uri.parse('https://api.jigsawstack.com/v1/ai/sql');

final res = await http.post(url, headers: headers, body: data);
final status = res.statusCode;
if (status != 200) throw Exception('http.post error: statusCode= $status');

print(res.body);
}

import java.io.IOException
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

val MEDIA_TYPE = "application/json".toMediaType()

val requestBody = "{\"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"

val request = Request.Builder()
.url("https://api.jigsawstack.com/v1/ai/sql")
.post(requestBody.toRequestBody(MEDIA_TYPE))
.header("Content-Type", "application/json")
.header("x-api-key", "your-api-key")
.build()

client.newCall(request).execute().use { response ->
if (!response.isSuccessful) throw IOException("Unexpected code $response")
response.body!!.string()
}

using System.Net.Http.Headers;
using System.Net.Http.Json;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.jigsawstack.com/v1/ai/sql");
request.Headers.Add("x-api-key", "your-api-key");
request.Content = JsonContent.Create(new
{
database = "postgresql",
prompt = "Find all transactions with amounts exceeding $10,000, sorted by transaction date",
sql_schema = "
        CREATE TABLE Transactions (
          transaction_id INT PRIMARY KEY, 
          user_id INT NOT NULL,
          total_amount DECIMAL(10, 2) NOT NULL, 
          transaction_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
          status VARCHAR(20) DEFAULT 'pending',
          FOREIGN KEY(user_id) REFERENCES Users(user_id)
        )
      "
});
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

Console.WriteLine(responseBody);
{
  "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
  }
}