How to Build a Text‑to‑SQL Chatbot with Vanna’s Open‑Source RAG Framework

Introduction

Vanna is an open‑source Python framework that combines Retrieval‑Augmented Generation (RAG) with large language models (LLMs) to automatically translate natural‑language questions into SQL queries, addressing the accuracy challenges of vanilla Text2SQL approaches.

What Is Vanna?

Vanna is released under the MIT license, available on GitHub, and can be installed via pip install vanna. It provides a RAG pipeline that enriches LLM prompts with database metadata, documentation, and example SQL statements to improve SQL generation correctness.

How Vanna Works (RAG Principle)

The framework first builds a vector store (the “RAG model”) from database DDL, documentation, and sample SQL pairs. When a user asks a question, Vanna retrieves relevant context from this vector store, assembles an enhanced prompt, and passes it to the LLM, which generates and executes the SQL.

Getting Started

Install Vanna

import vanna
from vanna.remote import VannaDefault
vn = VannaDefault(model='model_name', api_key='api_key')

Train the RAG Model Use one of the supported training methods:

DDL statements: vn.train(ddl="CREATE TABLE my_table (id INT, name TEXT)") Documentation strings: vn.train(documentation="Our business defines XYZ as ABC") SQL‑question pairs:

vn.train(question="What is the average age?", sql="SELECT AVG(age) FROM customers")

Automatic plan from information schema:

df = vn.run_sql("SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE table_schema='chatdata'")
plan = vn.get_training_plan_generic(df)
vn.train(plan=plan)

Ask Questions After training, query the database with natural language:

vn.ask("What are the top 10 albums by sales?")

Customization

Vanna can be extended to use custom LLMs or vector stores by subclassing the provided classes. Example:

from vanna.openai.openai_chat import OpenAI_Chat
from vanna.chromadb.chromadb_vector import ChromaDB_VectorStore
class MyVanna(ChromaDB_VectorStore, OpenAI_Chat):
    def __init__(self, config=None):
        ChromaDB_VectorStore.__init__(self, config=config)
        OpenAI_Chat.__init__(self, config=config)

vn = MyVanna(config={'api_key':'sk-...', 'model':'gpt-4-...'})

For databases not natively supported, implement a run_sql function that returns a pandas.DataFrame and assign it to vn.run_sql.

Testing the Chatbot

With a MySQL instance containing sales data, the full workflow (account creation, model training, and query) produces both the generated SQL and its result, as shown in the console screenshots.

Web App & Visualization

Vanna includes a Flask‑based web application for interactive querying and result visualization using Plotly. Launch it with:

from vanna.flask import VannaFlaskApp
app = VannaFlaskApp(vn)
app.run()

The web UI displays query results, charts, and provides simple APIs for managing the RAG model and visualizations.

Limitations & Future Outlook

Current limitations stem mainly from insufficient training data for the RAG model, affecting accuracy in some cases. Vanna’s roadmap aims to improve correctness, interactive capabilities (clarification, follow‑up questions), and autonomy (triggering workflows), moving closer to an AI data analyst.