Every engineer knows the distinct dread of a non-technical colleague messaging on Slack with a "quick data question". Two hours later, you are elbow-deep in legacy PostgreSQL tables, deciphering why a column named status_final_v2_really contains three different spelling variations of "pending".
Turning natural language into working SQL is one of the most practical tasks an LLM can perform. It is also remarkably easy to botch. Handing an entire database schema to a raw frontier model usually results in hallucinated table joins, invented foreign keys, or a context window choked with irrelevant DDL.
Vanna AI is an open-source Python framework designed specifically to fix this problem through Retrieval-Augmented Generation (RAG). Instead of hoping an LLM memorises your database dialect and company-specific jargon on the fly, Vanna systematically indexes your schemas, documentation, and verified SQL queries to produce reliable, high-accuracy queries.
What is Vanna AI?
Vanna AI is an MIT-licensed Python framework that automates high-accuracy text-to-SQL translation using a modular RAG pipeline. Rather than feeding raw database catalogues into a standard prompt, Vanna trains a vector store on three discrete assets: your data definition language (DDL), free-form documentation (such as business logic explanations), and verified question-SQL reference pairs.
When a user submits a natural language question, Vanna retrieves only the relevant schema context and historical query patterns before prompting the model. It then optionally executes the resulting SQL against your target database, returning clean pandas DataFrames and automatic Plotly visualisations.
[User Natural Language Prompt]
│
▼
┌───────────────────────────┐
│ Vector Store Retrieval │ <── Trained on: DDL, Docs,
│ (ChromaDB / Qdrant / etc) │ Golden SQL Pairs
└─────────────┬─────────────┘
│ (Relevant Context Only)
▼
┌───────────────────────────┐
│ LLM SQL Generator │ (OpenAI, Anthropic,
│ │ or Local Ollama)
└─────────────┬─────────────┘
│ (Synthesised SQL Query)
▼
┌───────────────────────────┐
│ Target Database │ (Postgres, Snowflake,
│ & Visualisation │ DuckDB, BigQuery)
└───────────────────────────┘
The Core Architecture: RAG Over Metadata
Most naive text-to-SQL implementations fail because real-world databases are untidy. A production enterprise warehouse might sport 300 tables, idiosyncratic abbreviations, and soft-deleted rows that require precise filtering.
Vanna structures your metadata into three distinct vectorised buckets:
1. DDL Statements: Table definitions, constraints, types, and primary/foreign keys.
2. Context Documentation: Plain-English explanations of business metrics (for example: "An 'active subscriber' is a user whose subscription has not lapsed within 30 days").
3. Golden SQL Pairs: Curated, verified pairs of natural language prompts and corresponding validated queries.
When a query arrives, Vanna's retrieval engine runs a similarity search to gather the most pertinent DDL chunks and the closest existing golden queries. If you ask about monthly recurring revenue, Vanna pulls the exact financial tables and past revenue queries rather than swamping the LLM with user session logs or inventory data.
Getting Started: Local Setup with Ollama and ChromaDB
Vanna uses an abstract, modular class structure. You can mix and match components: use OpenAI or local models via Ollama, pair them with ChromaDB or Qdrant, and connect to PostgreSQL, Snowflake, DuckDB, or MySQL.
Here is a fully local, privacy-conscious implementation running on your machine:
pip install "vanna[chromadb,ollama]" psycopg2-binary
import vanna
from vanna.chromadb import ChromaDB_VectorStore
from vanna.ollama import Ollama
# 1. Compose your custom Vanna class combining local RAG + local LLM
class LocalVanna(ChromaDB_VectorStore, Ollama):
def __init__(self, config=None):
ChromaDB_VectorStore.__init__(self, config=config)
Ollama.__init__(self, config={'model': 'mistral'})
vn = LocalVanna()
# 2. Connect to your database
vn.connect_to_postgres(
host='localhost',
dbname='analytics',
user='postgres',
password='secretpassword',
port=5432
)
# 3. Train the vector store with your DDL and business rules
vn.train(ddl="""
CREATE TABLE customers (
id SERIAL PRIMARY KEY,
name VARCHAR(255),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
is_active BOOLEAN DEFAULT TRUE
);
""")
vn.train(documentation="Active customers have is_active set to TRUE.")
vn.train(
question="How many active customers registered this month?",
sql="""SELECT count(id) FROM customers
WHERE is_active = true
AND date_trunc('month', created_at) = date_trunc('month', current_date);"""
)
# 4. Ask a question
result_sql = vn.generate_sql("Show me the count of active users joined this month")
print(result_sql)
# 5. Run the query directly
df = vn.run_sql(result_sql)
print(df)
Architectural Comparison
| Feature / Metric | Zero-Shot Raw Prompting | Naive ReAct Agents | Vanna AI Framework |
|---|---|---|---|
| Token Consumption | Massive (Requires full schemas) | Variable (High, back-and-forth loops) | Minimal (Retrieves only relevant DDL) |
| Hallucination Risk | High on complex schema joins | Moderate (Can get stuck in loops) | Low (Anchored by Golden SQL pairs) |
| Schema Scalability | Fails on large databases (>50 tables) | Struggles with broad context | Handles thousands of tables cleanly |
| Data Privacy | Sends raw data if prompted directly | Often runs unconstrained queries | Only metadata and schema are indexed |
| Deployment Flexibility | Cloud-bound | Often cloud-dependent | Fully air-gapped / local capable |
Why Vanna Stands Out
Developer consensus across GitHub discussions and machine learning forums highlights one overwhelming bottleneck in autonomous analytics: LLMs do not inherently know how your team calculates specific business figures.
If your warehouse marks cancelled orders with status = -1 while another team uses deleted_at IS NOT NULL, a generalist model cannot guess that policy without context. Vanna treats database documentation and SQL history as first-class citizens. By allowing teams to continuously train the vector layer on verified historical pull requests and vetted queries, the accuracy improves incrementally over time.
Furthermore, Vanna does not require sending your actual row-level database contents to an external API. Only schema structures, documentation strings, and historical queries are vectorised, keeping underlying customer records protected within your perimeter.
For technical teams seeking to build automated reporting bots or eliminate repetitive ad-hoc querying, Vanna provides a robust, production-ready foundation that bypasses the fragility of unguided SQL generation.