TL;DR
text2sql là một SDK Python text-to-SQL kiểu agent, build trên LangChain Deep Agents. Thay vì xây pipeline RAG để vector-index schema rồi prompt model, framework này đưa LLM đúng một tool — execute_sql — cộng với một connection string, và để model tự khám phá schema, draft query, đọc lỗi, tự sửa trong cùng một vòng lặp. Kết quả zero-shot trên Spider: 19/20 = 95%. Thêm một scenario làm rõ một câu hỏi mơ hồ: 20/20 = 100%. Repo MIT, mới ~26 star, chưa có release tag — sớm nhưng đáng theo dõi.
What's new
Đa phần các framework text-to-SQL hiện hành (Dataherald, Wren AI, datrics, Vanna…) đều theo cùng một công thức: vector-hóa schema/DDL, semantic search ra những bảng có vẻ liên quan, đẩy chúng vào prompt, gọi model một lần, kiểm tra lỗi, retry. text2sql vứt bỏ toàn bộ tầng tiền xử lý đó.
Tác giả mở README bằng đúng câu chốt vấn đề: "Until recently, LLMs couldn't reliably chain more than a handful of tool calls before losing the thread." Tới 2026, frontier model có thể chain hàng trăm tool call mà không mất mạch — nên chuyển công việc "chọn bảng nào liên quan" từ RAG pipeline sang chính cái agent loop là khả thi.
Build cụ thể: dùng Deep Agents làm harness, nhưng tắt các middleware mặc định (filesystem, sub-agents, planning). Chỉ giữ lại context compaction (tóm tắt tool call cũ khi loop dài) và Anthropic prompt caching (tiết kiệm token). Agent có hai công cụ: execute_sql để chạy SQL trực tiếp, và lookup_example tùy chọn để lấy domain rule từ một file scenarios.md khi cần.
Why it matters
Nếu pattern này nhân rộng được, nó tiết kiệm rất nhiều thứ cho team data:
- Không phải bảo trì vector index của schema. Schema warehouse thay đổi mỗi sprint; reindex liên tục là một loại nợ kỹ thuật ai từng vận hành đều biết.
- Không cần semantic layer. dbt metrics layer, LookML, Cube — tất cả là công cụ mạnh nhưng đắt thời gian dựng. text2sql ngầm bảo: bạn có thể bỏ qua nếu chấp nhận chi phí token cao hơn cho mỗi câu hỏi.
- Self-correcting là first-class. Stock LangChain SQL agent có 4 tool (
sql_db_list_tables,sql_db_schema,sql_db_query_checker,sql_db_query); text2sql gộp tất cả vào một loop duy nhất, đẩy độ phức tạp về phía model thay vì phía orchestrator.
Đánh đổi rõ ràng: token spend cao hơn. Mỗi câu hỏi là một agent loop, không phải one-shot prompt. Anthropic prompt caching giúp giảm bớt nhưng không xóa được phần này.
Technical facts
| Property | Value |
|---|---|
| License | MIT |
| Language | Python (100%) |
| Built on | LangChain Deep Agents |
| Models hỗ trợ | Anthropic Claude, OpenAI |
| DBs hỗ trợ | PostgreSQL, MySQL, SQLite, SQL Server, Snowflake, mọi SQLAlchemy-compatible DB |
| Middleware | Context compaction + Anthropic prompt caching (chỉ vậy) |
| Tools agent dùng | execute_sql, lookup_example (optional) |
| Spider zero-shot | 19/20 (95%) |
| Spider + 1 scenario | 20/20 (100%) |
| Repo signals | 26 stars, 4 forks, 21 commits, 0 releases (early-stage) |
Cài đặt và chạy:
pip install "text2sql[anthropic]"from text2sql import TextSQL
engine = TextSQL("postgresql://user:pass@localhost/mydb")
result = engine.ask("Which customers have spent more than $10K this year?")
print(result.sql) # SQL đã được verify
print(result.data) # kết quả queryComparison
| Approach | Schema retrieval | Setup overhead | Token cost / query |
|---|---|---|---|
| RAG-based (Dataherald, Wren, datrics) | Vector index DDL, semantic search | Cao — phải build & maintain index | Thấp (one-shot prompt) |
| Semantic layer (dbt metrics, Cube) | Curated metric definitions | Rất cao — yêu cầu data team đầu tư | Thấp |
| LangChain SQL agent (stock) | 4 tool: list_tables, schema, checker, query | Trung bình | Trung bình |
| text2sql (Deep Agents) | Agent tự explore qua execute_sql | Tối thiểu — chỉ cần connection string | Cao (multi-turn agent loop) |
Lưu ý benchmark: 95–100% là trên classic Spider. Spider 2.0 (enterprise variant) khó hơn nhiều — GPT-4 chỉ giải được ~6%. text2sql chưa công bố số liệu trên Spider 2.0 hay BIRD, nên đừng vội kết luận "giải quyết xong text-to-SQL".
Use cases
- BI nội bộ / "ask your warehouse": dựng chatbot Slack hỏi Postgres/Snowflake mà không phải dựng vector DB hay semantic layer trước.
- On-call engineering: truy vấn observability/metrics DB bằng tiếng Anh từ CLI.
- Prototype nhanh: trước khi commit vào framework nặng (Vanna, Dataherald, Wren), thử xem agent loop tự nó đã đủ tốt chưa cho schema của bạn.
- Schema thay đổi liên tục: startup early-stage, schema migrate hàng tuần — RAG index tốn công maintain hơn lợi ích nó mang lại.
Limitations & pricing
- Token spend: mỗi câu hỏi là multi-turn agent loop trên frontier model. Caching giúp nhưng không miễn phí.
- Schema scale chưa kiểm chứng: benchmark là 80 bảng / 20 DB. Warehouse 1000+ bảng (Snowflake enterprise) chưa có data.
- Frontier-model only: tác giả nói thẳng — cần Claude/GPT-class model. Local 8B/13B sẽ không chain được tool call đủ sâu.
- Spider, không phải Spider 2.0: kết quả 95–100% trên benchmark cũ; Spider 2.0 enterprise chưa được test.
- Maturity: 26 star, 21 commit, 0 release tag, 0 issue — còn rất sớm. Đừng đẩy thẳng vào prod.
- Giá: SDK MIT, free. Chi phí thực tế = API bill Anthropic/OpenAI.
What's next
Hai thứ đáng theo dõi: (1) số liệu trên benchmark khó hơn (Spider 2.0, BIRD) — đây là test thật cho luận điểm "không cần RAG"; (2) MCP integration để auto-generate scenario từ trace — nếu hoạt động, framework có thể tự học các domain rule mà không cần con người viết tay scenarios.md.
Rộng hơn, text2sql là một datapoint của một trend lớn hơn: khi tool-calling horizon của frontier model tăng từ vài chục lên vài trăm, nhiều RAG pipeline mà chúng ta xây 2023–2025 sẽ collapse thành agent loop trực tiếp. text-to-SQL chỉ là domain dễ thấy nhất vì có ground truth (SQL chạy hoặc không) và benchmark sẵn (Spider).
Nguồn: Text2SqlAgent/text2sql-framework, LangChain OSS announcement, LangChain Deep Agents docs, LangChain SQL agent docs.
