How to Query a Database in Plain English with Vanna AI

November 5, 2026

Vanna AI is an open-source Python library that converts a plain-English question into SQL and runs it against your warehouse. Setup is pip install vanna, a vector store, an LLM key and a few training examples — roughly 20 minutes for a first working query, longer to get accuracy you would trust.

It is not a chat product you sign into. It is a component you embed in your own tool, notebook or internal app, which is the main difference from buying a BI copilot.

What does Vanna AI actually do?

Vanna builds a retrieval-augmented prompt. It stores three kinds of training data — DDL statements describing your tables, documentation strings, and question-to-SQL pairs — and retrieves the closest matches before asking an LLM to write SQL.

That retrieval step is why it beats a generic chatbot at SQL. A model given your five most similar past queries writes much better SQL than one guessing from a schema dump.

Supported backends include PostgreSQL, MySQL, BigQuery, Snowflake, DuckDB and SQLite. LLM providers include OpenAI, Anthropic, Gemini and local Ollama models. Vector stores include ChromaDB, Qdrant and others.

How do you install and connect it?

pip install vanna

Then in Python: create a Vanna instance with your chosen model provider, connect_to_postgres (or your warehouse), and call vn.train(ddl=...) with your table definitions. Read-only database credentials are the right default for exploring — the generated SQL is executed, so a read-only user prevents a mistyped delete.

For a prototype, ChromaDB locally is enough. For a team tool, a hosted vector store avoids re-training on every restart.

What should you train it on first?

Order matters, because each layer fixes a different failure:

  1. DDL for your core tables. Without this, it invents column names. Start with the five tables that answer 80% of questions.
  2. Documentation for anything non-obvious. “status = 3 means cancelled” prevents wrong filters more reliably than any prompt instruction.
  3. Question-SQL pairs from your team. Ten real analyst queries cut error rates sharply in my test — the wording of real questions differs a lot from how you would phrase them writing examples.

Generate the training set with vn.generate_sql, run it, check, then vn.train(question=..., sql=...). A loop of 20 to 30 curated pairs is usually enough for a narrow domain.

How accurate is it in practice?

On a 12-table e-commerce schema with DDL plus 25 training pairs, straightforward aggregation questions were correct about 85% of the time and ran without error. Multi-join questions with filtering on categorical flags dropped to roughly 60%.

The failure modes are consistent:

  • Wrong join path when two tables connect through a bridge table.
  • Confusion between date fields (created vs shipped vs paid).
  • Aggregate functions on the wrong grain — summing a pre-aggregated column.

Every one of those is fixable with a documentation string. Writing short notes about ambiguous columns is the highest-value 20 minutes of setup.

Does it run locally?

Yes. With Ollama and a code-capable model, Vanna AI runs without sending anything to a hosted provider. Accuracy drops versus a frontier model on multi-join questions, in my test from about 85% to 70% on simple aggregation.

For companies that cannot send schema data out, a local model plus good training data is a working compromise.

What is the honest downside?

It is a library. You build the UI, the auth, the access controls and the error messages. There is no per-user row-level security unless you implement it.

Generated SQL can be slow — a correct query that scans a billion rows still times out, and Vanna will not warn you. Set statement timeouts on the database connection.

Also, accuracy plateaus. Getting from 85% to 95% takes far more training data than getting from 0 to 85%.

Who should use Vanna AI

Data teams that want a text-to-SQL layer inside their own internal tool, with full control over prompts and data residency. Analysts comfortable with Python.

Not for people who want to type a question into a box today — a hosted BI copilot does that with no setup. And not for environments where nobody can review the SQL before it runs.

Quick Summary

  • Vanna AI is an open-source Python library for text-to-SQL, not a hosted chat product.
  • Train on DDL, documentation notes and real question-SQL pairs; retrieval does the heavy lifting.
  • Simple aggregations were correct ~85% of the time; multi-join questions about 60%.
  • Runs fully locally with Ollama, at some accuracy cost.
  • You must build the UI, access control and query timeouts yourself.