Squrve: A Unified and Modular Framework for Complex Real-World Text-to-SQL Tasks
Yihan Wang, Peiyu Liu, Runyu Chen, Jiaxing Pu · 2025
Read Squrve: A Unified and Modular Framework for Complex Real-World Text-to-SQL Tasks by Yihan Wang, Peiyu Liu, Runyu Chen, Jiaxing Pu (2025) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2510-24102.txt.
Introduction
Yihan Wang and four co-authors introduce Squrve, a framework that turns research methods for text to SQL into a usable system. Text to SQL lets a user ask a question in plain words and get a database query back. Many methods score well in studies, yet firms lack good tools to combine and deploy them in real products.
Squrve sets a shared way to call each method and breaks the work into seven small actor parts that can be teamed in workflows. Tests on common benchmarks show team workflows beat the single methods they came from. The authors release the code and argue this path helps with complex real world queries.
Catalog record
| CREATOR | Yihan Wang, Peiyu Liu, Runyu Chen, Jiaxing Pu |
|---|---|
| YEAR | 2025 |
| COLLECTION | PAPERS |
| FORMAT | TXT |
| FILE SIZE | 30 KB |
| VERSION | 1.0 |
| LICENSE | http://creativecommons.org/licenses/by/4.0/ |
| RIGHTS | CC BY |
| SOURCE | arXiv |
Source: https://arxiv.org/abs/2510-24102
Browse the full library · About the Tower of Babel
Full text
The opening of the work, from the library's hosted text:
Squrve: A Unified and Modular Framework for Complex Real-World Text-to-SQL Tasks Yihan Wang, Peiyu Liu, Runyu Chen, Jiaxing Pu Abstract Text-to-SQL technology has evolved rapidly, with diverse academic methods achieving impressive results. However, deploying these techniques in real-world systems remains challenging due to limited integration tools. Despite these advances, we introduce Squrve, a unified, modular, and extensive Text-to-SQL framework designed to bring together research advances and real-world applications. Squrve first establishes a universal execution paradigm that standardizes invocation interfaces, then proposes a multi-actor collaboration mechanism based on seven abstracted effective atomic actor components. Experiments on widely adopted benchmarks demonstrate that the collaborative workflows consistently outperform the original individual methods, thereby opening up a new effective avenue for tackling complex real-world queries. The codes are available at https://github.com/Satissss/Squrve . Figure 1: The overview of the Squrve framework. Squrve unifies diverse methods under a general execution paradigm and supports task-specific multi-actor collaboration, bridging academic research and real-world systems. 1 Introduction Text-to-SQL Liu et al. 2024 ; Shi et al. 2025 ; Hong et al. 2025 aims to translate natural language questions into accurate SQL queries, enabling non-expert users to access and manipulate data effortlessly. As an emerging querying paradigm, Text-to-SQL facilitates real-world database-driven AI agent applications, such as conversational business intelligence tools or automated decision-support assistants Wang et al. 2022a ; Xu et al. 2020 . However, most existing studies tend to focus on specific aspects of the problem, e.g., schema linking Pourreza and Rafiei 2023 , decoding strategy Pourreza et al. 2025 , or data augmentation Talaei et al. 2024 . In contrast, real-world Text-to-SQL problems are inherently more complex, where multiple challenges often coexist. This discrepancy highlights the need for a unified framework that can systematically integrate, compare, and extend different methods, enabling complementary strengths from diverse approaches to be effectively combined and applied to practical tasks. There are two critical challenges that hinder the development of such a unified framework. Challenge 1: lack of unified integration mechanism . Existing methods are typically designed for specific settings, each with distinct data formats, input–output interfaces, or dependency requirements. This fragmentation makes it difficult to combine or switch models across diverse scenarios, resulting in limited cross-task adaptability Gan et al. 2021b and poor scalability to heterogeneous real-world environments. Challenge 2: tackling diverse and co-occuring difficulties in real-world scenarios . Real-world queries often involve multiple difficulties ( e.g., domain adaptation and multi-table reasoning) that no single model can fully address. Integrating complementary strengths across models is therefore crucial but remains difficult without coordinated interfaces and execution pipelines. These challenges are often overlooked, widening the gap between academic research and real-world Text-to-SQL applications. To address these challenges, we propose Squrve, a unified, modular, and extensive Text-to-SQL framework that systematically addresses the challenges of diverse real-world applications by fully leveraging academic advances. For Challenge 1, Squrve introduces a universal Text-to-SQL execution paradigm that standardizes invocation interfaces and parameter configurations. Through its modular architecture, Squrve reproduces and integrates existing advanced academic models, which achieves effective generalization across diverse Text-to-SQL task scenarios. For Challenge 2, Squrve abstracts and formalizes seven atomic Actor components, each representing a distinct Text-to-SQL capability validated in prior research. Building on these components, Squrve introduces a multi-actor collaboration mechanism that effectively fuses their complementary strengths, allowing different actors to interact and cooperate when handling complex real-world queries. To evaluate Squrve’s performance, we conduct comprehensive experiments on the widely adopted Spider Yu et al. 2018 and Bird Li et al. 2023c benchmarks, systematically assessing the execution accuracy of the generated SQL queries. The results indicate that Squrve faithfully reproduces baseline methods while preserving their performance, which achieves or even surpasses the originally reported results based solely on open-source models. Furthermore, the ensemble methods built upon multiple actors consistently outperform the original individual methods, demonstrating the effectiveness of compositional reasoning through the integration of complementary actors. These findings highlight that Squrve bridges the gap between academic research and real-world applications, establishing a pathway for advancing practical development. 2 Architecture Design To generalize academic techniques to diverse real-world scenarios, Squrve proposes a unified, modular and extensible framework comprising four key modules. Specifically, the data module standardizes different dataset formats into unified structures; the actor module defines critical atomic Text-to-SQL capability and enables their collaborative composition; the task module serves as isolated containers that enable concurrent processing; and the execution module orchestrates the complete Text-to-SQL execution with global control. 2.1 Data Module To standardize data operations, Squrve first defines unified structures for database schemas and query instances, following the field naming conventions of mainstream datasets such as Spider, Bird, and others. Building on this foundation, the Data module provides universal preprocessing methods that transform both user-uploaded private datasets and built-in benchmarks into standardized formats for seamless access in downstream stages. Database schema preprocessing. Existing datasets typically store complete large-scale database schemas in a single centralized file, which often exceeds the LLM’s context window. To alleviate this limitation, this module decomposes centralized database schemas into parallel column-level files, where each file serves as a semantic unit containing complete column metadata without additional storage overhead, enabling efficient retrieval of relevant subsets via RAG methods. Query instance preprocessing. Squrve constructs and maintains more than 200 chain-of-thought (CoT) exemplars from existing benchmark datasets, which can be embedded and indexed for efficient vector retrieval. For new complex queries, this module retrieves semantically similar exemplars and assembles them into complete CoT prompts, effectively enhancing the quality of SQL generation. For queries that depend on external documents, this module extracts key contextual information, such as concept definitions and metric calculation formulas, using carefully designed chain-of-thought strategies. 2.2 Actor Module To better handle complex real-world queries, Squrve decomposes the Text-to-SQL process into seven atomic actors, each capturing a fundamental capability that has been validated in prior research (see Table 1 ). Compared with complete end-to-end workflows, these actors generalize more flexibly across tasks by focusing on the core functional components. Building on these actors, Squrve introduces a multi-actor collaboration mechanism that integrates actors derived from different methods, enabling them to work jointly and share complementary strengths within unified workflows. For clarity in subsequent discussion, an actor can be described as a black-box that generates the required SQL end-to-end: SQL=f_{\text{actor}}(Q,S,C|M), (1) where Q denotes user queries, S denotes the database schemas, C represents valuable contextual information specific to the query, and M indicates the LLM backbone. Next, we will introduce the atomic actors and their collaboration mechanism in detail. 2.2.1 Atomic Actors This section provides a detailed explanation of the seven atomic actors in Squrve, outlining their individual roles and functional contributions within the overall Text-to-SQL workflow. Actors Methods Key Challenges Reduce LinkAlign Wang et al. 2025 large-scale and multi-database Parse LinkAlign; RSL-SQL Cao et al. 2024 ambiguous queries and redundant schemas Generate DIN-SQL; CHESS Talaei et al. 2024 efficient and high-quality SQL generation Decompose DIN-SQL; MAC-SQL Wang et al. 2024 Chain-of-Thought for complex queries Scale CHESS; CHASE-SQL Pourreza et al. 2025 diverse and high-quality decoding strategies Optimize CHASE-SQL; OpenSearch Xie et al. 2025 ; effective and broader database feedback Select OpenSearch; MCS-SQL Lee et al. 2024 ; accurate gold SQL identification Table 1: Summary of the prior methods that each Actor in Squrve builds upon,