Tell me Waii: Jupyter and gen AI

Gunther Hagleitner
Published in
4 min readNov 23, 2023


Robot looking at a number of charts and visualizations.

Well, the ‘Waii’ is clear actually. The ‘how’ is what I’m going to get into here.

Waii ( is an easy to use text-to-SQL API. It solves some of the more challenging issues in the space: Large databases (100s of tables), achieving high accuracy and customization to your business context.

Let’s start with a problem statement: You have a warehouse that captures sales and customer data and you’re trying to find out which US state has the most customer growth.

Since you want to use Waii, there are a few lines of setup code you need.

(Side note: I’ve run this on, but any Jupyter deployment will work.)

Code that installs and initializes the waii sdk.

The first statement will install the sdk. The other statements will simply initialize the API. The key is stored using google’s user data api.

Code to generate a query from instructions expressed in natural language.

This is really it. A single call to generate the query. And the data you want is stated as an instruction in plain English.

If you’re wondering, yes, this assumes that you have already connected Waii to your own warehouse. If you hadn’t, you could either do this thru another API call, or use the UI / CLI to do it. Everything else Waii does automatically behind the scenes.

The sql object that is returned has a wealth of information. Let’s take a look at the query first.

SQL query corresponding to the natural language statement.

The query is compiled, optimized, formatted, and ready to go. If you don’t want to read through all of it, here’s a step-by-step description of the query.

Description of the query in plain english.

This sounds sensible and matches the above query nicely. Here’s another thing you can do: Get any semantic context that was considered when generating the query.

Semantic context of the query.

There are multiple month related columns in the data set. Someone put additional information about D_MOY into the system. That helps the LLM pick the right column for the query. There’s also a rule about how Item revenue is defined. (Useful, but that’s not being applied in this query.)

You can also use Waii to run the query. Here’s how. The output is put into a pandas data frame for further exploration.

Result set of the query. Shows states and percentages.

Alright, that answers the original question and didn’t take too much effort. Let’s see if we can visualize this result and display the information on a US map.

Code that asks for a plot of the data.
US map with the percent increase information visualized through a color scheme.

Flashy, but there’s really no additional information that’s revealed by putting the data on a map. It doesn’t look like there is a broader geographic context behind the numbers. Maybe not the best visualization. Let’s have Waii choose the chart type.

Code that asks for a chart of the data.
Bar chart representing the data.

Much better. That gives a pretty clear indication of what the customer growth looks like!

And that’s it for a quick tour. There’s a lot more — you can get descriptions of the warehouse, tune the performance of the query, translate between database engines, ... But I hope this gives you a quick overview of what’s possible.

If you’re interested and want to try Waii for yourself: Request access at We’ll set up with an api key, playground, sample data and full docs.