The /generate_sql endpoint converts natural language questions into SQL queries. It allows you to interact with your database using natural language.

📘
When to use this

You want to translate a natural language question into SQL, without running or summarizing the result yet.

You are building a workflow where SQL needs to be reviewed, modified, or approved before execution.

You want to debug or fine-tune the generated SQL separately from other steps.

You want to chain SQL generation with manual or automated execution (e.g., send SQL to /run_sql, or to /generate_summary).

For an all-in-one experience (question → SQL → result → summary), use the /ask endpoint instead.

Basic Usage

To generate a SQL query, send a request with your question:

// Request
{
  "question": "Show me all customers"
}

// Response
{
  "id": "1fbc0d64-1c58-45b2-a990-9183bbbcf913",
  "sql": "SELECT * FROM \"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
{
  "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 /run_sql endpoint to execute the query and get results
Use the returnSqlDialect: true parameter 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 response
code: An error code indicating the type of issue encountered:
- NON_SQL_QUERY: The question cannot be translated to SQL because it's unrelated to data querying
- NO_DEPLOYMENT_FOUND: No active deployment was found for the project
- POLLING_TIMEOUT: 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 SQL
explanationQueryId: 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 /stream_explanation endpoint to receive a detailed explanation response streamed as events.