What Vanna actually does
Vanna AI is frequently described as a "natural language to SQL" tool. That description is accurate but incomplete — and the gap between the accurate description and the complete one is where most implementations go wrong.
At its core, Vanna is a training-based system. You give it your database schema and a set of question-and-SQL pairs. It learns to map natural language questions to syntactically correct SQL queries against your specific database. That's the hard part, and Vanna does it reliably.
Out of the box, Vanna returns three things: the generated SQL, a raw data table, and a basic auto-generated Plotly chart. That's its job description, and it executes it well. The question is what you expected it to do — and whether those expectations were reasonable.
The narrative layer
is not Vanna's job
Vanna does not interpret results. It does not generate insights. It does not tell you whether the numbers it just retrieved are good, bad, or worth acting on. The SQL layer is real and reliable. The meaning layer is entirely absent.
This is a common source of disappointment in implementations. A user asks "What was our RevPAR for Q1 compared to last year?" Vanna produces correct SQL, returns the data, and generates a bar chart. The user wanted an answer — they got a dataset.
Vanna found the data. Claude read it. The two together produce something neither delivers alone.
This is not a criticism of Vanna. It's a precise description of what the tool is. Understanding the boundary between what Vanna does and what requires a separate layer is the prerequisite for building anything useful with it.
Adding the intelligence layer
In the SO Labs hotel BI platform, Vanna handles the SQL translation. Claude handles the interpretation. The pattern is straightforward: Vanna's query result is passed to Claude with a prompt that asks for structured analysis — headline finding, interpretation, business implication, recommended action.
The result is something neither tool delivers alone. Vanna produces data with precision. Claude produces meaning from data. The combination gives you the answer to the question you actually asked — not just a dataset shaped like an answer.
This architecture applies beyond hotel BI. Any system where you need natural language access to structured data, and where the output needs to be interpretable rather than just queryable, benefits from the same pattern: Vanna for the data layer, a language model for the insight layer.
Why the SO Labs build
uses an iframe
One architectural decision in the SO Labs hotel BI platform deserves explanation: Vanna is embedded as an iframe rather than a native Retool component. This was a deliberate choice, not a limitation.
Vanna has its own session management, its own rendering logic for SQL and results, and its own conversational state. Integrating it natively into Retool's component model — wiring its query flow into Retool's state management — turned out to be more brittle than it was worth. Every integration attempt created friction between two frameworks with different assumptions about how data flows and how UI responds.
The iframe is the honest solution. It gives Vanna its own context, lets it do what it does well, and surfaces the result inside the dashboard without pretending the integration is tighter than it is. There's also an argument that Vanna, as a natural language querying tool, is really a separate product that deserves its own interface. The iframe acknowledges that reality.