{"id":10336,"library":"vanna","title":"Vanna","description":"Vanna is a Python library that enables users to generate SQL queries from natural language, visualize results, and get answers, now with enterprise security and user-aware permissions. Version 2.0.2 is a complete rewrite, focusing on better support for agentic models and an improved user-aware framework. The library maintains an active development pace with frequent updates.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/vanna-ai/vanna","tags":["LLM","SQL generation","NLP2SQL","Database AI","Agentic","Data Analytics"],"install":[{"cmd":"pip install vanna","lang":"bash","label":"Basic Install"}],"dependencies":[{"reason":"Required for using OpenAI models (e.g., GPT-4o). Install with 'pip install \"vanna[openai]\"'.","package":"openai","optional":true},{"reason":"A common vector database backend for Vanna. Install with 'pip install \"vanna[chromadb]\"'.","package":"chromadb","optional":true},{"reason":"Default database for `VannaDefault` for local testing. Install with 'pip install \"vanna[duckdb]\"'.","package":"duckdb","optional":true}],"imports":[{"note":"Vanna 2.0 introduces `VannaDefault` for simplified local setup, replacing direct instantiation of `Vanna` or a custom class based on `VannaBase`, `LLM`, and `VectorStore` components for quickstarts.","wrong":"from vanna import Vanna","symbol":"VannaDefault","correct":"from vanna.local import VannaDefault"},{"note":"Used for building custom Vanna instances by inheriting from LLM and VectorStore components.","symbol":"VannaBase","correct":"from vanna.base import VannaBase"},{"note":"Required for integrating with OpenAI LLM models.","symbol":"OpenAI_Chat","correct":"from vanna.openai import OpenAI_Chat"},{"note":"Required for integrating with ChromaDB as a vector store.","symbol":"ChromaDB_VectorStore","correct":"from vanna.chromadb import ChromaDB_VectorStore"}],"quickstart":{"code":"import os\nfrom vanna.local import VannaDefault\nimport pandas as pd\n\n# For local testing, VannaDefault uses DuckDB and OpenAI as defaults.\n# Ensure OPENAI_API_KEY is set in your environment.\n# pip install \"vanna[duckdb]\" \"vanna[openai]\"\n\n# Initialize VannaDefault with your OpenAI API key and preferred model\nvn = VannaDefault(\n    model='gpt-4o',\n    api_key=os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY'), # Replace with actual key or set env var\n    path='my_vanna_db' # Path for local ChromaDB and DuckDB storage\n)\n\n# Connect to a database (DuckDB is default for VannaDefault)\nvn.run_sql_query(\"CREATE TABLE sales (id INT, product TEXT, amount INT)\")\nvn.run_sql_query(\"INSERT INTO sales (id, product, amount) VALUES (1, 'Apple', 100), (2, 'Banana', 150)\")\n\n# Train Vanna with DDL, documentation, and example questions/SQL\nvn.train(ddl=\"CREATE TABLE employees (id INT, name TEXT, salary INT)\")\nvn.train(question=\"What are the total sales for each product?\", sql=\"SELECT product, SUM(amount) FROM sales GROUP BY product\")\nvn.train(sql=\"SELECT * FROM sales\", df=pd.DataFrame({'id': [1], 'product': ['Apple'], 'amount': [100]}))\n\n# Ask a question\nquestion = \"Show me the sum of sales for each product\"\nsql = vn.generate_sql(question=question)\nprint(f\"Generated SQL: {sql}\")\n\n# Run the generated SQL\nif sql:\n    results = vn.run_sql(sql=sql)\n    print(f\"Query Results:\\n{results}\")\nelse:\n    print(\"Could not generate SQL for the question.\")","lang":"python","description":"This quickstart demonstrates how to use `VannaDefault` for a local setup. It initializes Vanna with OpenAI and a local DuckDB, trains it with schema and example questions, and then generates and runs SQL for a natural language query. Ensure you have the `OPENAI_API_KEY` environment variable set or replace the placeholder."},"warnings":[{"fix":"Refer to the Vanna 2.0 documentation and migration guides. Re-architect your Vanna instance creation using the new inheritance model (e.g., `class MyVanna(VectorStore, LLM, VannaBase)`) or use `VannaDefault` for quick setups. Update method calls like `train_sql` to `train`.","message":"Vanna 2.0.0 represents a complete architectural rewrite. Code written for pre-2.0 versions will likely break due to significant API changes, especially around `Vanna` class instantiation, training methods, and connector configuration.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Install Vanna with the necessary extras, e.g., `pip install \"vanna[openai]\"` for OpenAI integration, `pip install \"vanna[chromadb]\"` for ChromaDB, or `pip install \"vanna[duckdb]\"` for local DuckDB use with `VannaDefault`.","message":"Vanna requires additional packages for specific LLMs (e.g., OpenAI, Anthropic) and Vector Stores (e.g., ChromaDB, Pinecone, pgvector). The base `pip install vanna` does not include these.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your LLM API key is correctly configured. For OpenAI, set the `OPENAI_API_KEY` environment variable or pass it directly in the `config` dictionary when initializing your LLM component, e.g., `OpenAI_Chat(config={'api_key': 'YOUR_KEY'})`.","message":"API keys for LLMs (like OpenAI) are critical for Vanna's functionality. Incorrect or missing keys will lead to authentication errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install Vanna with the OpenAI extra: `pip install \"vanna[openai]\"`.","cause":"The optional `openai` dependency was not installed along with `vanna`.","error":"ModuleNotFoundError: No module named 'vanna.openai'"},{"fix":"Set the `OPENAI_API_KEY` environment variable correctly, or pass a valid API key via the `config` dictionary during LLM initialization.","cause":"The OpenAI (or other LLM) API key is missing, incorrect, or expired.","error":"AuthenticationError: Incorrect API key provided"},{"fix":"In Vanna 2.0.0+, all training methods are consolidated under `vn.train()`. Use `vn.train(sql=...)`, `vn.train(ddl=...)`, `vn.train(question=...)`, etc.","cause":"Attempting to use pre-2.0 training methods like `train_sql` or `train_ddl` with Vanna 2.0.0+.","error":"AttributeError: 'Vanna' object has no attribute 'train_sql'"},{"fix":"Ensure that your custom Vanna class's `__init__` method correctly calls the `__init__` methods of its parent components with a `config` dictionary, even if empty. Example: `ChromaDB_VectorStore.__init__(self, config=config)`.","cause":"When creating a custom Vanna instance by inheriting from `VannaBase`, `LLM`, and `VectorStore` components, the `__init__` methods of the base classes (like `ChromaDB_VectorStore` or `OpenAI_Chat`) expect a `config` dictionary.","error":"TypeError: __init__ missing 1 required positional argument: 'config'"}]}