post
https://example.com/api/v2/generate_sql
Converts a natural language question into a SQL query
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
The /v2/generate_sql endpoint converts natural language questions into SQL queries. It allows you to interact with your database using natural language.
Basic Usage
To generate a SQL query, send a request with your question:
// Request
{
"projectId": 1,
"question": "Show me all customers"
}
// Response
{
"id": "1fbc0d64-1c58-45b2-a990-9183bbbcf913",
"sql": "SELECT * FROM \"olist_customers_dataset\"",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}Getting Both Wren SQL and Dialect SQL
Use the returnBothSqlDialect parameter to receive both the original Wren SQL and the database-specific dialect SQL:
// Request
{
"projectId": 1,
"question": "Show me top 10 customers with their details",
"returnBothSqlDialect": true
}
// Response
{
"id": "1fbc0d64-1c58-45b2-a990-9183bbbcf913",
"sql": "SELECT \"customer_id\" AS \"Customer_ID\", \"customer_unique_id\" AS \"Customer_Unique_ID\", \"customer_city\" AS \"Customer_City\", \"customer_state\" AS \"Customer_State\" FROM \"olist_customers_dataset\" LIMIT 10",
"dialectSql": "SELECT olist_customers_dataset.customer_id AS `Customer_ID`, olist_customers_dataset.customer_unique_id AS `Customer_Unique_ID`, olist_customers_dataset.customer_city AS `Customer_City`, olist_customers_dataset.customer_state AS `Customer_State` FROM (SELECT __source.customer_city AS customer_city, __source.customer_id AS customer_id, __source.customer_state AS customer_state, __source.customer_unique_id AS customer_unique_id FROM `wrenai-saas-staging`.sample_dataset_ecommerce.olist_customers_dataset AS __source) AS olist_customers_dataset LIMIT 10",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}Understanding the Response Fields
sql: Clean, readable Wren SQL that's optimized for understandingdialectSql: Database-specific SQL that will actually be executed, including schema prefixes, table references, and database-specific syntax
When to Use returnBothSqlDialect
returnBothSqlDialect- Debugging: Compare the generated Wren SQL with the actual executed SQL
- Transparency: See exactly what SQL will run against your database
- Integration: Use the
dialectSqldirectly in your database tools if needed
SQL Dialect Compatibility
The returnSqlDialect parameter returns only the dialect SQL:
// Request
{
"projectId": 1,
"question": "Show me all customers",
"returnSqlDialect": true
}
// Response
{
"id": "1fbc0d64-1c58-45b2-a990-9183bbbcf913",
"sql": "SELECT olist_customers_dataset.customer_id, olist_customers_dataset.customer_unique_id FROM `project.dataset.olist_customers_dataset`",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}Conversation Context
You can use the threadId returned in the response to ask follow-up questions while maintaining context:
// Follow-up question
{
"projectId": 1,
"question": "list top 10 only",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}
// Response
{
"id": "2589615b-abbd-48b0-926f-128faa96a87e",
"sql": "SELECT * FROM \"olist_customers_dataset\" ORDER BY \"customer_id\" ASC LIMIT 10",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}Executing Queries
Once you have the SQL, you can:
- Pass the SQL to the
/v2/run_sqlendpoint to execute the query and get results - Use the
returnSqlDialect: trueparameter to get SQL in your database's native dialect and run it directly in your database
Non-SQL Query Handling
If your question can't be converted to SQL, you'll receive an error response with the following fields:
id: A unique identifier for the error responsecode: An error code indicating the type of issue encountered:NON_SQL_QUERY(HTTP 400): The question cannot be translated to SQL because it's unrelated to data queryingNO_DEPLOYMENT_FOUND(HTTP 400): No active deployment was found for the projectPOLLING_TIMEOUT(HTTP 500): The operation timed out while waiting for a response from the AI service
error: A human-readable description explaining why the query couldn't be translated to SQLexplanationQueryId: An identifier you can use to get a more detailed explanation
// Example 1: Asking question "hello"
{
"id": "e593369b-e222-4435-b874-dc10edb12a96",
"code": "NON_SQL_QUERY",
"error": "Vague greeting unrelated to schema, SQL, or user guide; no specific intent identified.",
"explanationQueryId": "475afc1f-7950-4bc7-a248-a7da394d137a"
}
// Example 2: Asking question "what could you do"
{
"id": "75c13d09-6f86-4e79-a00e-a4f85f73f2d7",
"code": "NON_SQL_QUERY",
"error": "User asks about Wren AI's features and capabilities, unrelated to database schema.",
"explanationQueryId": "71b016c5-42bb-4897-82d6-46f9b0bf7d94"
}Use the explanationQueryId with the /v2/stream_explanation endpoint to receive a detailed explanation response streamed as events.