FlexSQL: Flexible Exploration and Execution Make Better Text-to-SQL Agents
TL;DR Highlight
고정된 파이프라인 대신 추론 중 언제든 DB를 탐색·실행할 수 있는 Text-to-SQL 에이전트로 Spider2.0 벤치마크에서 gpt-o3, DeepSeek-R1 기반 시스템을 더 작은 모델로 능가
Who Should Read
Snowflake, BigQuery 같은 대규모 데이터 웨어하우스에서 자연어 → SQL 변환 파이프라인을 구축하거나 개선하려는 백엔드/데이터 엔지니어. LLM 기반 DB 쿼리 자동화 도구를 만드는 AI 엔지니어에게도 유용.
Core Mechanics
- 기존 Text-to-SQL 시스템은 스키마를 한 번만 조회하고 고정된 순서로 SQL을 생성하는데, FlexSQL은 추론 과정 어느 시점에서든 GetSchema, GetTableCol, GetColValues, FindRows, SQLExecutor, PythonExecutor 총 6개 도구로 DB를 자유롭게 탐색·실행 가능
- 자연어 쿼리의 모호성을 다루기 위해 diversity-enforced sampling(의도적으로 서로 다른 해석을 강제하는 샘플링)으로 K개의 플랜을 병렬 생성하고, 실행 결과 기준 majority voting으로 최종 답변 선택
- 각 플랜을 SQL 또는 Python 중 더 적합한 언어로 구현하는 bilingual generation 지원 — Python이 독점적으로 문제를 푸는 경우가 Spider2-SQLite에서 최대 27.6%에 달함
- 오류 발생 시 코드 레벨 수정(최대 3회)만 아니라, 잘못된 테이블 선택이나 플랜 자체 오류면 Plan Generation 단계로 backtracking해 스키마 재탐색 후 플랜 전체를 다시 작성하는 2단계 repair 메커니즘 보유
- Python으로 생성된 최종 답변은 Python-to-SQL 트랜스파일러로 SQL로 변환 — gpt-oss-20b가 87%를 처리하고 나머지를 gpt-oss-120b가 처리해 전체 96.77% 변환 성공률 달성
- FlexSQL의 탐색 패러다임을 Claude Code에 skill로 패키징해 적용했을 때 Spider2-Snow Pass@1이 58.3% → 66.0%로 7.7%p 절대 향상, 범용 코딩 에이전트에도 적용 가능성 확인
Evidence
- Spider2-Snow에서 gpt-oss-120b K=16 기준 Majority@K 65.44% 달성 — DSR-SQL + DeepSeek-R1(63.80%), ReFoRCE + gpt-o3(62.89%) 모두 능가
- Spider2-SQLite에서 gpt-oss-20b의 Pass@1 50.37%가 gpt-oss-120b 기반 ReFoRCE(45.19%), DSR-SQL(48.15%) 두 베이스라인을 모두 초과 — 더 작은 모델로 더 큰 모델 기반 시스템 제압
- Python 인터프리터 제거 시 Majority@8이 120b 기준 64.44% → 52.59%(-11.85%p), 20b 기준 54.07% → 42.22%(-11.85%p)로 가장 큰 성능 하락 발생
- 테이블 레벨 스키마 링킹 F1에서 FlexSQL + oss-120b Best of 8이 95.26%로, ReFoRCE + o4+o3+o4 mini(80.03%), DSR-SQL + DeepSeek-V3(82.65%)를 크게 앞서며 precision 95.46% 기록
How to Apply
- LLM에게 DB 메타데이터 전체를 컨텍스트로 한번에 주는 대신, 스키마 이름 목록만 초기값으로 주고 GetSchema → GetTableCol → GetColValues 순서로 필요할 때마다 호출하도록 tool-use 프롬프트를 설계하면 대형 DB에서 컨텍스트 오버플로우 없이 정확한 스키마 링킹 가능
- SQL 생성 시 모호한 쿼리에는 하나의 해석만 시도하지 말고 'Plan A: 테이블 X만 사용, Plan B: 테이블 X+Y 조인, Plan C: 추가 테이블 포함' 식으로 K개 플랜을 생성한 뒤 각각 실행하고 결과가 동일한 그룹에 투표하는 majority voting 패턴을 적용
- 복잡한 집계나 반복 로직이 필요한 쿼리는 SQL 직접 생성 대신 Python(pandas, numpy)으로 먼저 구현하고 결과가 검증되면 SQL로 트랜스파일하는 2단계 접근법을 파이프라인에 추가 — 특히 재귀적 상태 의존 계산이나 다단계 집계에서 효과적
Code Example
# FlexSQL 스타일 Text-to-SQL 에이전트 프롬프트 패턴 예시
SYSTEM_PROMPT = """
You are a text-to-SQL agent. You have access to these tools:
- GetSchema(schema_name): List all tables in a schema
- GetTableCol(table_name): Get columns and sample values
- GetColValues(column, table): Get distinct values in a column
- FindRows(term, column, table): Keyword search in column
- SQLExecutor(sql): Execute SQL and return results
- PythonExecutor(code): Execute Python with DB access
Rules:
1. Start with only schema names. Explore incrementally.
2. ALWAYS inspect actual column values before writing filters.
3. Generate K=3 diverse plans covering different table choices.
4. For each plan, choose SQL or Python based on complexity.
5. If execution fails with plan-level error, backtrack and re-explore.
"""
USER_QUERY = "Find patents filed in Q1 2014 in materials science"
# 에이전트가 따를 탐색 순서 예시:
# Step 1: GetSchema('PATENT_DB') → 테이블 목록 확인
# Step 2: GetTableCol('TECH_CLASS') → 컬럼 구조 파악
# Step 3: GetColValues('field_code', 'TECH_CLASS') → 실제 값 확인 (MS-01~MS-09)
# Step 4: SQLExecutor('SELECT COUNT(*) FROM FILING_INFO WHERE filing_date BETWEEN ...')
# Step 5: 3개 플랜 생성 (인용 테이블 범위별)
# Step 6: 각 플랜 SQL/Python으로 구현
# Step 7: Majority voting으로 최종 답 선택
# Diversity-enforced sampling 프롬프트 예시
DIVERSITY_PROMPT = """
Generate plan {k} that is DIFFERENT from these existing plans:
{existing_plans}
Explore alternative:
- Different table combinations
- Different join paths
- Different interpretations of ambiguous terms
"""
Terminology
Related Papers
Show HN: adamsreview – better multi-agent PR reviews for Claude Code
Claude Code에서 최대 7개의 병렬 서브 에이전트가 각각 다른 관점으로 PR을 리뷰하고, 자동 수정까지 해주는 오픈소스 플러그인이다. 기존 /review나 CodeRabbit보다 실제 버그를 더 많이 잡는다고 주장하지만 커뮤니티에서는 복잡도와 실효성에 대한 회의론도 나왔다.
How Fast Does Claude, Acting as a User Space IP Stack, Respond to Pings?
Claude Code에게 IP 패킷을 직접 파싱하고 ICMP echo reply를 구성하도록 시켜서 실제로 ping에 응답하게 만든 실험으로, 'Markdown이 곧 코드이고 LLM이 프로세서'라는 아이디어를 네트워크 스택 수준까지 밀어붙인 재미있는 사례다.
Show HN: Git for AI Agents
AI 코딩 에이전트(Claude Code 등)가 수행한 모든 툴 호출을 자동으로 추적하고, 어떤 프롬프트가 어느 코드 줄을 작성했는지 blame까지 가능한 버전 관리 도구다.
Principles for agent-native CLIs
AI 에이전트가 CLI 도구를 더 잘 사용할 수 있도록 설계하는 원칙들을 정리한 글로, 에이전트가 CLI를 도구로 활용하는 빈도가 높아지면서 이 설계 방식이 실용적으로 중요해지고 있다.
Agent-harness-kit scaffolding for multi-agent workflows (MCP, provider-agnostic)
여러 AI 에이전트가 서로 역할을 나눠 협업할 수 있도록 조율하는 scaffolding 도구로, Vite처럼 설정 없이 빠르게 멀티 에이전트 파이프라인을 구성할 수 있다.
Show HN: Tilde.run – Agent sandbox with a transactional, versioned filesystem
AI 에이전트가 실제 프로덕션 데이터를 건드려도 롤백할 수 있는 격리된 샌드박스 환경을 제공하는 도구로, GitHub/S3/Google Drive를 하나의 버전 관리 파일시스템으로 묶어준다.
Related Resources
Original Abstract (Expand)
Text-to-SQL over large analytical databases requires navigating complex schemas, resolving ambiguous queries, and grounding decisions in actual data. Most current systems follow a fixed pipeline where schema elements are retrieved once upfront and the database is only revisited for post-hoc repair, limiting recovery from early mistakes. We present FlexSQL, a text-to-SQL agent whose core design principle is flexible database interaction: the agent can explore schema structure, inspect data values, and run verification queries at any point during reasoning. FlexSQL generates diverse execution plans to cover multiple query interpretations, implements each plan in either SQL or Python depending on the task, and uses a two-tiered repair mechanism that can backtrack from code-level errors to plan-level revisions. On Spider2-Snow, using gpt-oss-120b, FlexSQL achieves a 65.4\% score, outperforming strong open-source baselines that use stronger, larger models such as gpt-o3 and DeepSeek-R1. When integrated into a general-purpose coding agent (as skills in Claude Code), our approach yields over 10\% relative improvement on Spider2-Snow. Further analysis shows that flexible exploration and flexible execution jointly contribute to the effectiveness of our approach, highlighting flexibility as a key design principle. Our code is available at: https://github.com/StringNLPLAB/FlexSQL