File size: 4,468 Bytes
90d89c6 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 |
---
pipeline_tag: text-ranking
library_name: transformers
---
# GRAST-SQL: Scaling Text-to-SQL via LLM-efficient Schema Filtering with Functional Dependency Graph Rerankers
GRAST-SQL is a lightweight, open-source schema-filtering framework that scales Text-to-SQL to real-world, very wide schemas by compacting prompts without sacrificing accuracy. It ranks columns with a query-aware LLM encoder enriched by values/metadata, reranks them via a graph transformer over a functional-dependency (FD) graph to capture inter-column structure, and then guarantees joinability with a Steiner-tree spanner to produce a small, connected sub-schema. Across Spider, BIRD, and Spider-2.0-lite, GRAST-SQL delivers near-perfect recall with substantially higher precision than CodeS, SchemaExP, Qwen rerankers, and embedding retrievers, maintains sub-second median latency on typical databases, scales to 23K+ columns, and cuts prompt tokens by up to 50% in end-to-end systems—often with slight accuracy gains—all while using compact models.
This model was presented in the paper [Scaling Text2SQL via LLM-efficient Schema Filtering with Functional Dependency Graph Rerankers](https://huggingface.co/papers/2512.16083).
Code: https://github.com/thanhdath/grast-sql
## System flow
### Datasets
- **Spider**: [Spider Evaluation Dataset](https://huggingface.co/datasets/griffith-bigdata/GRAST-SQL-Spider)
- **BIRD**: [BIRD Training/Evaluation Dataset](https://huggingface.co/datasets/griffith-bigdata/GRAST-SQL-BIRD)
- **Spider-2.0-lite**: [Spider 2.0-lite Eval Dataset](https://huggingface.co/datasets/griffith-bigdata/GRAST-SQL-Spider2.0-lite)
### Models
- **GRAST-SQL 0.6B**: [GRAST-SQL 0.6B BIRD](https://huggingface.co/griffith-bigdata/GRAST-SQL-0.6B-BIRD-Reranker)
- **GRAST-SQL 4B**: [GRAST-SQL 4B BIRD](https://huggingface.co/griffith-bigdata/GRAST-SQL-4B-BIRD-Reranker)
- **GRAST-SQL 8B**: [GRAST-SQL 8B BIRD](https://huggingface.co/griffith-bigdata/GRAST-SQL-8B-BIRD-Reranker)
More models can be found in [Huggingface collection](https://huggingface.co/collections/griffith-bigdata/grast-sql)
## Sample Usage
To apply GRAST-SQL to your own database, follow these two simple steps:
### Step 1: Initialize (ONE-TIME per database) - Functional Dependency Graph Construction & Metadata Completion
Extract schema information, generate table/column meanings, predict missing keys, and build the functional dependency graph:
```bash
python init_schema.py \
--db-path /home/datht/mats/data/spider/database/concert_singer/concert_singer.sqlite \
--output concert_singer.pkl \
--model gpt-4.1-mini
```
**Arguments:**
- `--db-path`: Path to your SQLite database file (required)
- `--output`: Output path for the graph pickle file (default: `schema_graph.pkl`)
- `--model`: OpenAI model to use for meaning generation and key prediction (default: `gpt-4.1-mini`)
**Note:** Make sure your OpenAI API key is set in `.env`.
### Step 2: Filter Top-K Columns
Use the GRAST-SQL model to filter the most relevant columns for a given question:
```bash
python filter_columns.py \
--graph concert_singer.pkl \
--question "Show name, country, age for all singers ordered by age from the oldest to the youngest." \
--top-k 5
```
**Arguments:**
- `--graph`: Path to the graph pickle file from Step 1 (required)
- `--question`: Natural language question about the database (required)
- `--top-k`: Number of top columns to retrieve (default: 10)
- `--checkpoint`: Path to GNN checkpoint (default: `griffith-bigdata/GRAST-SQL-0.6B-BIRD-Reranker/layer-3-hidden-2048.pt`)
- `--encoder-path`: Path to encoder model (default: `griffith-bigdata/GRAST-SQL-0.6B-BIRD-Reranker`)
- `--max-length`: Maximum sequence length (default: 4096)
- `--batch-size`: Batch size for embedding generation (default: 32)
- `--hidden-dim`: Hidden dimension for GNN (default: 2048)
- `--num-layers`: Number of GNN layers (default: 3)
## Citation
```bibtex
@misc{hoang2025scalingtext2sqlllmefficientschema,
title={Scaling Text2SQL via LLM-efficient Schema Filtering with Functional Dependency Graph Rerankers},
author={Thanh Dat Hoang and Thanh Tam Nguyen and Thanh Trung Huynh and Hongzhi Yin and Quoc Viet Hung Nguyen},
year={2025},
eprint={2512.16083},
archivePrefix={arXiv},
primaryClass={cs.DB},
url={https://arxiv.org/abs/2512.16083},
}
``` |