ADAPT-SQL: Adaptive Decomposed And Pipeline-driven Text-to-SQL

A state-of-the-art Text-to-SQL system achieving 93.7% Execution Accuracy on the Spider benchmark using a fully local LLM pipeline. Built as a course project for Semantic Web Mining (CSE 573) at Arizona State University.

No commercial API keys required. Runs entirely on local models via Ollama.

Table of Contents

1. Results
2. The Text-to-SQL Problem
3. Architecture Overview
4. Key Innovations
5. Pipeline Deep Dive
6. Ablation Studies
7. Fine-Tuning with GRPO and SFT
8. Literature Analysis
9. Quick Start
10. Interactive UI
11. Configuration
12. Project Structure
13. Citation

Results

Performance on Spider Benchmark

Metric	Score
Execution Accuracy (EX)	93.7%
Exact-Set-Match (EM)	35.6%
Valid SQL Rate	100%
Execution Success	99.3%

Comparison with State-of-the-Art

Rank	Method	Model	Spider EX	Cost/Query
1	ADAPT-SQL (Ours)	Qwen3-Coder (Local)	93.7%	$0.00
2	MiniSeek	-	91.2%	-
3	DAIL-SQL + GPT-4	GPT-4	86.6%	~$0.12
4	DIN-SQL + GPT-4	GPT-4	85.3%	~$0.15
5	RESDSQL	Fine-tuned T5	84.1%	N/A
6	C3-SQL	GPT-4	82.3%	~$0.10

Performance by Query Complexity

Complexity	Queries	Execution Accuracy
EASY	283	96.1%
NON_NESTED_COMPLEX	596	93.8%
NESTED_COMPLEX	121	88.4%

The Text-to-SQL Problem

Text-to-SQL converts natural language questions into executable SQL queries against a relational database. This is the core technology behind natural language interfaces to databases, chatbots that query structured data, and AI assistants that answer questions from enterprise data warehouses.

Why It's Hard

flowchart TD
    NL[Natural Language Question] --> CH{Challenges}

    CH --> SC[Schema Complexity\n100+ tables, ambiguous names]
    CH --> AM[Linguistic Ambiguity\nSame question, multiple valid SQLs]
    CH --> NE[Nested Logic\nSubqueries, set operations, CTEs]
    CH --> IM[Implicit Knowledge\nDomain conventions not in schema]

    SC --> ERR[Incorrect SQL]
    AM --> ERR
    NE --> ERR
    IM --> ERR

Loading

Existing Approaches and Their Limitations

Approach	How It Works	Limitation
Fine-tuned models (RESDSQL, DTS-SQL)	Train seq2seq on (NL, SQL) pairs	Expensive training, poor generalization
Prompt-based (DIN-SQL, DAIL-SQL)	Feed schema + examples to GPT-4	$$$ per query, non-reproducible
Multi-agent (MAC-SQL, XiYan-SQL)	Multiple LLM agents collaborate	High latency, complex orchestration
RL-trained (SQL-R1)	Reward model on execution correctness	Requires massive compute for training
ADAPT-SQL (Ours)	Adaptive pipeline with local LLMs	Best of all: free, fast, accurate

Architecture Overview

ADAPT-SQL implements an 11-step pipeline that systematically transforms natural language into SQL. Unlike uniform approaches, it classifies query complexity and routes to specialized generators.

flowchart TD
    Q[Natural Language Query] --> S1

    subgraph Pipeline ["ADAPT-SQL Pipeline"]
        S1[1. Schema Linking\nThree-Layer] --> S2[2. Complexity\nClassification]
        S2 --> S3[3. Preliminary SQL\nPrediction]
        S3 --> S4[4. Example Retrieval\nFAISS + Reranking]
        S4 --> S5[5. Strategy Routing]

        S5 -->|Easy| S6A[6a. Few-Shot\nGeneration]
        S5 -->|Medium| S6B[6b. NatSQL\nIntermediate]
        S5 -->|Hard| S6C[6c. Decomposed\nGeneration]

        S6A & S6B & S6C --> S7[7. SQL Validation]
        S7 --> S8[8. Feedback Retry]
        S8 --> S9[9. Normalization]
        S9 --> S10[10. Execution]
        S10 --> S11[11. Evaluation]
    end

    S11 --> SQL[Executable SQL]

Loading

End-to-End Flow

sequenceDiagram
    autonumber
    participant U as User
    participant SL as Schema Linker
    participant CL as Classifier
    participant GEN as Generator
    participant VAL as Validator
    participant DB as Database

    U->>SL: "Find students with GPA > avg"
    SL->>SL: String match + LLM + validation
    SL->>CL: Linked schema (2 tables, 6 cols)
    CL->>CL: Rule-based complexity check
    CL->>GEN: NON_NESTED_COMPLEX
    GEN->>GEN: NatSQL intermediate + SQL
    GEN->>VAL: SELECT name FROM student WHERE gpa > (SELECT AVG(gpa)...)
    VAL->>DB: Execute
    DB-->>VAL: Results match expected
    VAL-->>U: Verified SQL

Loading

Key Innovations

1. Three-Layer Schema Linking

A multi-stage approach that reduces schema errors by 40% compared to single-pass methods:

flowchart LR
    Q[Query] --> L1[Layer 1\nFuzzy String Match]
    L1 -->|4.2 tables\n18.3 cols| L2[Layer 2\nLLM Semantic Analysis]
    L2 -->|2.8 tables\n9.1 cols| L3[Layer 3\nPost-Validation]
    L3 -->|2.3 tables\n6.2 cols| OUT[Final Schema]

Loading

Layer	Method	Avg Tables	Avg Columns	Purpose
1	Fuzzy token matching	4.2	18.3	Cast wide net, high recall
2	LLM semantic analysis	2.8	9.1	Focus selection, high precision
3	Connectivity validation	2.3	6.2	Prune disconnected elements

2. Adaptive Complexity Routing

Queries are classified into three tiers, each routed to a specialized generator:

flowchart TD
    Q[Query] --> RC{Rule-Based\nClassifier}

    RC -->|Single table\nbasic WHERE| EASY[EASY]
    RC -->|JOINs, GROUP BY\naggregations| MED[NON_NESTED_COMPLEX]
    RC -->|Subqueries\nEXCEPT, INTERSECT| HARD[NESTED_COMPLEX]

    EASY --> FS[Few-Shot Prompting\n96.1% accuracy]
    MED --> NS[NatSQL Intermediate\n93.8% accuracy]
    HARD --> DG[Decomposed Generation\n88.4% accuracy]

Loading

Complexity	Strategy	How It Works
EASY	Few-Shot	Direct SQL from examples, minimal reasoning needed
NON_NESTED_COMPLEX	NatSQL	Translate to intermediate representation first, then to SQL
NESTED_COMPLEX	Decomposed	Break into sub-questions, solve each, compose final SQL

3. DAIL-SQL Structural Reranking

Enhanced example selection combining multiple similarity dimensions for better in-context learning:

Combined Score = 0.5 x Semantic + 0.3 x Structural + 0.2 x Style

• Semantic: FAISS embedding similarity between query pairs
• Structural: SQL skeleton pattern matching (JOIN types, clause structure)
• Style: Column/table naming conventions and formatting patterns

4. Validation-Feedback Retry

Automated error correction that recovers 15%+ of initially incorrect predictions:

flowchart TD
    SQL[Generated SQL] --> EX{Execute}
    EX -->|Error| AN[Analyze Error Type]
    AN --> FB[Build Feedback Prompt\nwith error + schema context]
    FB --> RE[Regenerate with Feedback]
    RE --> EX
    EX -->|Success| OUT[Final SQL]
    EX -->|Max retries| LAST[Return best attempt]

Loading

Retry	Queries	EX Before	EX After	Recovery
0	812	94.2%	94.2%	-
1	142	78.3%	91.5%	+13.2%
2	46	65.2%	84.8%	+19.6%

Pipeline Deep Dive

Step-by-Step Breakdown

Step	Module	Input	Output	Technique
1	schema_linking.py	Query + full DB schema	Relevant tables/columns	Three-layer filtering
2	query_complexity.py	Query + linked schema	Complexity label	Rule-based classification
3	prel_sql_prediction.py	Query + schema	Draft SQL	Zero-shot LLM prediction
4	vector_search.py	Query embedding	Top-K similar examples	FAISS + structural reranking
5	routing_strategy.py	Complexity + draft SQL	Generation strategy	Routing logic
6a	few_shot.py	Query + examples	SQL (easy queries)	Direct prompting
6b	intermediate_repr.py	Query + examples	NatSQL then SQL	Intermediate language
6c	decomposed_generation.py	Query + examples	Sub-SQLs then composed	Divide-and-conquer
7	validate_sql.py	Generated SQL + schema	Validation result	Syntax + schema check
8	validation_feedback_retry.py	Failed SQL + error	Corrected SQL	Error-guided retry
9	sql_normalizer.py	Raw SQL	Normalized SQL	Formatting + deduplication
10	execute_compare.py	SQL + database	Execution result	SQLite execution
11	evaluation.py	Predicted vs gold results	EX / EM metrics	Result set comparison

Why an 11-Step Pipeline Beats End-to-End

flowchart LR
    subgraph E2E ["End-to-End (GPT-4 style)"]
        Q1[Query] --> LLM1[Single LLM Call] --> SQL1[SQL]
    end

    subgraph ADAPT ["ADAPT-SQL"]
        Q2[Query] --> P[11 Focused Steps] --> SQL2[SQL]
    end

    E2E --> R1[86% EX\n$0.12/query]
    ADAPT --> R2[93.7% EX\n$0.00/query]

Loading

• Each step has a narrow, testable responsibility
• Errors are caught and corrected at validation boundaries
• Complexity routing avoids over-engineering simple queries
• Local execution means zero API cost and full reproducibility

Ablation Studies

Impact of each component when removed from the full pipeline:

Configuration	EX	Impact
Full ADAPT-SQL	93.7%	-
w/o Three-Layer Schema Linking	87.2%	-6.5%
w/o Structural Reranking	88.9%	-4.8%
w/o NatSQL Intermediate	89.4%	-4.3%
w/o Validation-Feedback Retry	91.1%	-2.6%
w/o Rule-Based Complexity	92.1%	-1.6%
w/o SQL Normalization	92.8%	-0.9%

Schema linking contributes the most (6.5%), confirming that getting the right tables/columns is the single most important step. Structural reranking (4.8%) shows that example quality matters more than quantity for in-context learning.

Fine-Tuning with GRPO and SFT

Beyond the inference pipeline, ADAPT-SQL includes a fine-tuning module to train domain-adapted LLMs using the pipeline's own training data:

Training Approaches

flowchart LR
    subgraph SFT ["Supervised Fine-Tuning"]
        D1[Pipeline Training Data] --> QLoRA1[QLoRA on Qwen2.5-Coder-32B]
        QLoRA1 --> M1[SFT Model]
    end

    subgraph GRPO ["Group Relative Policy Optimization"]
        D2[Query + Multiple SQL Candidates] --> REW[4-Component Reward]
        REW --> QLoRA2[QLoRA + RL]
        QLoRA2 --> M2[GRPO Model]
    end

    M1 & M2 --> MERGE[Merge Checkpoints] --> OLLAMA[Export to Ollama]

Loading

GRPO Reward Components

Component	Weight	What It Measures
Format correctness	0.2	Valid SQL syntax
Execution success	0.3	Runs without error
Result accuracy	0.4	Output matches gold
Length penalty	0.1	Prefer concise SQL

Infrastructure

• Training hardware: Intel Gaudi accelerators (ASU SOL cluster)
• Base model: Qwen2.5-Coder-32B-Instruct
• Method: QLoRA (4-bit quantization, rank 64)
• Expected gain: +2-4% EX from domain-adapted weights stacking on pipeline improvements

Literature Analysis

This project includes a comprehensive analysis of 15 research papers spanning the Text-to-SQL landscape, with cross-referencing against ADAPT-SQL's design decisions:

Papers Surveyed

Category	Papers	Key Takeaway for ADAPT-SQL
Schema Linking	RESDSQL, LinkAlign, View-Oriented	Multi-layer linking beats single-pass
Multi-Agent	MAC-SQL, XiYan-SQL, DeepEye-SQL	Specialized agents per subtask improve accuracy
Retrieval/ICL	SAFE-SQL, AP-SQL, DAIL-SQL	Example quality (structural similarity) matters more than quantity
RL Training	SQL-R1, ExCoT	Execution reward is the strongest training signal
Robustness	Dr.Spider	Real-world queries need perturbation resistance

Technique Adoption

flowchart TD
    subgraph Adopted ["Adopted in ADAPT-SQL"]
        A1[Schema Ranking\nfrom RESDSQL]
        A2[Structural Reranking\nfrom DAIL-SQL]
        A3[Execution Retry\nfrom LitE-SQL]
        A4[Complexity Routing\nfrom AP-SQL]
        A5[NatSQL Intermediate\nfrom MAC-SQL decomposer]
    end

    subgraph Queued ["Queued for Next Iteration"]
        B1[Multi-Candidate Voting\nfrom XiYan-SQL]
        B2[Set-Op Detection\nfrom DeepEye-SQL]
        B3[Python-as-CoT\nfrom Pi-SQL]
    end

Loading

Full paper summaries, leaderboard comparisons, and gap analysis available in PAPERS/summary.md and PAPER_DOCUMENTATION.md.

Quick Start

Prerequisites

# Install Ollama and pull required models
ollama pull qwen3-coder       # Primary LLM
ollama pull nomic-embed-text  # Embeddings for FAISS

Installation

git clone https://github.com/shreerajbhamare/adapt-sql.git
cd adapt-sql

python -m venv venv
source venv/bin/activate

pip install -r requirements.txt

# Build vector store (first time only)
python utils/vector_store.py

Usage

from core.adapt_baseline import ADAPTBaseline

adapt = ADAPTBaseline(
    model="qwen3-coder",
    vector_store_path="./vector_store",
    enable_sql_normalization=True,
    enable_structural_reranking=True
)

result = adapt.run_full_pipeline(
    natural_query="Find students with GPA higher than average",
    schema_dict=schema,
    foreign_keys=foreign_keys,
    enable_retry=True,
    enable_execution=True,
    db_path="path/to/database.db",
    gold_sql=ground_truth_sql
)

print(f"Generated SQL: {result['final_sql']}")
print(f"Execution Accuracy: {result['step11']['execution_accuracy']}")

Interactive UI

streamlit run ui/app.py

Features:

• Single query mode with step-by-step pipeline visualization
• Batch evaluation mode for dataset-level benchmarking
• Multi-model comparison (swap LLMs and compare accuracy)
• Error analysis with failure categorization

Configuration

Parameter	Default	Description
model	qwen3-coder	Ollama model for generation
max_retries	2	Validation retry attempts
execution_timeout	30s	SQL execution timeout
enable_sql_normalization	True	Post-generation formatting
enable_structural_reranking	True	DAIL-SQL style reranking
schema_linking_table_threshold	0.6	Fuzzy match threshold
validation_fuzzy_threshold	0.7	Correction suggestion threshold

Project Structure

adapt-sql/
├── core/
│   └── adapt_baseline.py              # Main pipeline orchestrator
├── pipeline/
│   ├── schema_linking.py              # Three-layer schema linking
│   ├── query_complexity.py            # Complexity classification
│   ├── prel_sql_prediction.py         # Preliminary SQL
│   ├── vector_search.py              # FAISS example retrieval
│   ├── routing_strategy.py            # Strategy routing
│   ├── few_shot.py                    # Easy query generation
│   ├── intermediate_repr.py           # NatSQL generation
│   ├── decomposed_generation.py       # Nested query handling
│   ├── validate_sql.py               # SQL validation
│   ├── validation_feedback_retry.py   # Error retry loop
│   ├── sql_normalizer.py             # SQL normalization
│   ├── execute_compare.py            # Execution + comparison
│   └── evaluation.py                 # Metrics computation
├── utils/
│   ├── vector_store.py               # FAISS index build
│   ├── structural_similarity.py      # DAIL-SQL reranking
│   ├── fuzzy_schema_validator.py     # Fuzzy name matching
│   └── rule_based_complexity.py      # Classification rules
├── finetune/
│   ├── train_sft.py                  # Supervised fine-tuning
│   ├── train_grpo.py                 # GRPO reinforcement learning
│   └── INSTRUCTIONS.md               # Training on ASU SOL cluster
├── ui/
│   └── app.py                        # Streamlit interface
├── PAPERS/                           # 15 surveyed papers + analysis
├── PAPER_DOCUMENTATION.md            # Full technical writeup
├── RESULTS/                          # Benchmark results
└── vector_store/                     # FAISS embeddings + metadata

Citation

@software{adapt_sql_2026,
  title = {ADAPT-SQL: Adaptive Decomposed And Pipeline-driven Text-to-SQL},
  author = {Bhamare, Shreeraj and More, Sidessh},
  year = {2026},
  note = {Course project for CSE 573: Semantic Web Mining, Arizona State University},
  url = {https://github.com/shreerajbhamare/adapt-sql}
}

Acknowledgments

• Course: CSE 573 Semantic Web Mining, Arizona State University
• Spider Benchmark (Yu et al., 2018)
• DIN-SQL (Decomposed In-Context Learning)
• DAIL-SQL (Demonstration-Aligned SQL Generation)
• Ollama (Local LLM inference)
• ASU Research Computing (SOL cluster for fine-tuning)