Vanna AI Review: Text-to-SQL That Learns Your Schema

What it is: Vanna is an open-source Python framework that uses RAG plus an LLM to convert natural language to SQL. You train it once on your DDL, documentation strings, and a handful of golden query examples, and it generates accurate SQL for your specific warehouse.

How does RAG on your schema actually work?

Instead of fine-tuning a model, Vanna stores three kinds of training data as embeddings in a vector database: DDL statements (table and column definitions), documentation strings (what "churned" means at your company), and question–SQL pairs. When someone asks a question, Vanna retrieves the most similar items, packs them into the prompt, and lets the LLM write SQL grounded in your real schema rather than guesses.

vn.train(ddl="CREATE TABLE orders (id INT, customer_id INT, amount NUMERIC, ...)")
vn.train(documentation="'active customer' = ordered in the last 90 days")
vn.train(question="Monthly revenue this year?",
         sql="SELECT date_trunc('month', created_at), sum(amount) ...")

vn.ask("Which customers went inactive last quarter?")

Because the knowledge lives in the vector store, swapping the LLM (OpenAI, Anthropic, a local model) doesn't lose your training — it just changes who reads the retrieved context.

What does the training loop look like day to day?

The workflow is a feedback loop, not a one-time setup. Seed it with your DDL and 10–20 golden queries, ship it to a pilot group, then watch what it gets wrong. Every wrong answer becomes a corrected question–SQL pair added back with vn.train(), and that exact class of question is fixed for everyone from then on. Teams that treat the training set like a test suite — reviewed, versioned, growing — see accuracy climb steadily; teams that dump DDL and walk away plateau fast.

How accurate is Vanna AI?

It depends almost entirely on training data, not the model. On a cold start with only DDL, expect mediocre results on anything beyond simple lookups — real schemas encode business logic no LLM can infer. With good documentation and 30–100 curated question–SQL pairs covering your common query shapes, teams routinely report high-80s to 90s percent accuracy on recurring analyst questions. Novel, multi-step analytical questions still need a human to review the generated SQL, so surface the SQL alongside every answer.

Is Vanna AI free?

The core framework is free and MIT-licensed — you can self-host everything with a local vector store like ChromaDB and pay nothing except your LLM provider's API bill (or nothing at all with a local model). Vanna also offers hosted/paid options with a managed UI and hosted vector storage. For most data teams the open-source path is the sensible default: pip install vanna, ChromaDB, and your existing LLM key.

Should you self-host or use the hosted version?

Self-host when your schema or data is sensitive — everything (embeddings, training data, SQL execution) stays in your infrastructure, and only the retrieved prompt context goes to your chosen LLM, or nowhere if you run a local model. Choose the hosted offering when you want the packaged web UI and zero infrastructure. A common middle path: self-hosted library + the open-source Flask/Streamlit front ends Vanna ships for quick internal apps.

Install & configure

pip install vanna

Pick a vector store (ChromaDB, Pinecone, Qdrant) and an LLM (OpenAI, Anthropic, local). Train with vn.train(ddl=...), vn.train(documentation=...), and vn.train(question=..., sql=...) calls. Then call vn.ask(question). Connectors exist for Postgres, Snowflake, BigQuery, Redshift, and DuckDB.

Example usage

Stand up a Slack bot in an afternoon: an analyst asks "monthly revenue for product X this year" and the bot replies with a chart and the underlying SQL. Wrong answers? Add a corrected example to the training set and the next ask is right.

Author & links

Author: Vanna AI

Repo: github.com/vanna-ai/vanna

License: MIT

Related skills

For a full UI/BI experience instead of a Python library, see Wren AI.

← Back to Data Agents