Building SQL-of-Thought: Multi-Agentic Text-to-SQL with Guided Error Correction

You ask your database: "Show me customers who spent more than average last quarter."

The AI generates SQL. Executes it. Returns an error.

Tries again. Same error, different phrasing.

Third attempt. Still broken.

This happens constantly with Text-to-SQL systems. Even GPT-4 fails on complex joins, ambiguous columns, and aggregation logic. Most systems retry blindly, making the same mistakes in slightly different ways.

A recent paper from Max Planck Institute and AWS GenAI introduced SQL-of-Thought, a multi-agent framework that categorizes 31 types of SQL errors and fixes them systematically. It hits 91.59% accuracy on the Spider benchmark.

Instead of just explaining the research, I built a working demo to see how this approach handles real errors.

Here's what I learned.

The Problem with Single-Agent Text-to-SQL

Traditional approaches use one LLM call to generate SQL directly from natural language.

When the query fails, they retry. Maybe adjust the prompt. Try again.

No systematic understanding of what went wrong. No targeted fix based on error type.

Common failures include:

• Schema mismatches (wrong table or column names)
• Ambiguous column references (same name in multiple tables)
• Missing joins between related tables
• Incorrect aggregation functions
• Wrong filter conditions

The paper's insight: categorize errors into 31 types across 9 categories, then apply targeted corrections based on error classification.

Understanding the Paper's Architecture

Before diving into the demo, here's how SQL-of-Thought actually works.

Figure 1 from Research Paper - Multi-Agent Pipeline

The Multi-Agent Pipeline

The framework orchestrates six specialized agents in sequence:

1. Schema Linking Agent receives the natural language question and database schema, then identifies relevant tables, columns, primary keys, and foreign key relationships.
2. Subproblem Agent takes the schema-linked output and breaks the query into clause-level components: WHERE conditions, JOIN requirements, GROUP BY aggregations, ORDER BY sorting, HAVING filters, LIMIT clauses.
3. Query Plan Agent uses chain-of-thought reasoning to create a step-by-step execution plan. This agent thinks through the problem procedurally before writing any SQL.
4. SQL Agent converts the query plan into executable SQL, handling syntax and formatting.
5. DB Execution Engine runs the query against the database.
6. Correction Loop activates on failure:
   • Correction Plan Agent analyzes the error using the taxonomy, identifies root cause, generates fix strategy
   • Correction SQL Agent regenerates query based on correction plan
   • Loop repeats until success or max attempts reached

The key innovation: when errors occur, the system doesn't just retry. It diagnoses the error type and applies a targeted fix.

The Error Taxonomy

Figure 2 from Research Paper - Error Taxonomy

The correction system categorizes SQL failures into 9 major categories with 31 specific error types.

table 1 from Research Paper - Error Taxonomy

Why This Taxonomy Matters

Traditional systems see only execution errors: "column not found" or "ambiguous reference." They retry with slight variations, often repeating the same mistake.

SQL-of-Thought categorizes the error type and applies the known solution pattern. If it's ambiguous_col, add table prefixes. If it's join_missing, identify the join path through foreign keys. If it's agg_no_groupby, add GROUP BY for non-aggregated columns.

The taxonomy transforms debugging from guesswork into systematic diagnosis.

Building the Demo

I wanted to see this work with real data and real errors.

Database Choice

I used Chinook, a SQLite database modeling a music store. It has 11 tables: Artist, Album, Track, Invoice, Customer, Employee, and more. Realistic complexity with foreign keys and multiple join paths.

Tech Stack

• Backend: Node.js + Express + DuckDB (SQLite compatibility)
• Frontend: Vite + vanilla JavaScript
• LLM: OpenAI GPT-4o-mini (fast and cost-effective)
• Real-time updates: Server-Sent Events to stream each agent step

The 6 Specialized Agents

Agent Architecture - Image by Author

Following the paper's architecture, I built six specialized agents in Node.js:

{
  "SELECT": "Track.Name, SUM(revenue)",
  "FROM": "Track, InvoiceLine",
  "JOIN": "Track.TrackId = InvoiceLine.TrackId",
  "GROUP BY": "Track.Name",
  "ORDER BY": "revenue DESC",
  "LIMIT": "5"
}

The UI shows each agent's output in real-time. You watch schema linking, see the query plan being built, view generated SQL, and observe error correction when needed.

Demo 1: Simple Query Success

Let's start with a straightforward query.

Query: "What are the top 5 best-selling tracks by total revenue?"

Demo 1 - Simple Query Success - Image by Author

Here's what happens behind the scenes:

1. Schema Linking identifies the tables needed: Track (for names), InvoiceLine (for sales), and the relationship TrackId connecting them.
2. Subproblem decomposition breaks it into: SELECT track name and revenue sum, JOIN Track with InvoiceLine, GROUP BY track name, ORDER BY revenue descending, LIMIT to 5.
3. Query Plan reasons through the logic: start with Track table, join to InvoiceLine via TrackId, calculate revenue as UnitPrice × Quantity, aggregate per track, sort by total, take top 5.
4. SQL Generation produces:
   SQL Copy

   SELECT
     t.Name AS TrackName,
     SUM(il.UnitPrice * il.Quantity) AS TotalRevenue
   FROM Track t
   JOIN InvoiceLine il ON t.TrackId = il.TrackId
   GROUP BY t.Name
   ORDER BY TotalRevenue DESC
   LIMIT 5;

Result: ✅ Success in first attempt. 5 rows returned in 2.8 seconds.

This shows the pipeline working smoothly when no errors occur.

Demo 2: Ambiguous Column Error with Guided Correction

Now the interesting part.

Query: "Get all invoice items with their unit price and track unit price"

Demo 2 - Ambiguous Column Error - Image Generated by Author

The problem: Both InvoiceLine and Track tables have a UnitPrice column. The initial SQL failed with "ambiguous column reference."

How the correction worked:

1. Correction Plan Agent classified the error as schema_link.ambiguous_col
2. Ran DESCRIBE InvoiceLine and DESCRIBE Track to see actual schemas
3. Identified that both tables contain UnitPrice
4. Generated fix strategy: add table prefixes to disambiguate
5. Correction SQL Agent regenerated SQL with proper table aliases

Result: ✅ Success on second attempt after targeted correction.

Error Taxonomy in Action

Here's how the taxonomy guides corrections for different error types:

Error Categories and Solutions - Image by Author

Each category has a known solution pattern. The correction agent identifies the category and applies the appropriate fix.

Why This Approach Works

Limitations and Tradeoffs

SELECT DISTINCT State FROM Customer LIMIT 20;

Future Improvements

Several directions could enhance the demo:

• Fine-tuned models for specific agent roles. A small model trained on schema linking could reduce costs while maintaining accuracy.
• Query execution plan visualization. Show users how the database actually executes the generated SQL, not just the SQL itself.
• Support for more databases. PostgreSQL, MySQL, SQL Server each have dialect-specific quirks that need custom correction strategies.
• Interactive correction guidance. Let users provide hints when automatic correction fails, teaching the system new error patterns.
• Performance optimization tracking. Not just correctness; also measure query execution time and suggest index improvements.

Conclusion

Image Generated by Author Using AI

The SQL-of-Thought paper introduces a practical framework for reliable Text-to-SQL translation.

The key insight: categorize errors systematically and apply targeted fixes based on error type. This transforms SQL generation from a trial-and-error process into a diagnostic system.

Building the demo confirmed that multi-agent architecture with taxonomy-guided correction works on real data. The approach handles ambiguous columns, missing joins, wrong aggregations, and other common failures that break single-agent systems.

The 91.59% accuracy on the Spider benchmark isn't just a number. It represents a systematic approach to error handling that makes Text-to-SQL reliable enough for production use.