How-to

How to generate a cube SQL query with AI in Hubviz

Describe the data you want in plain language, pick the database tables and let the AI write the cube SQL query. Review it before applying.

Write what you want to see in plain language. The AI reads the structure of the tables you pick and returns the cube’s SQL query, ready to review.

When to use it

You know the business but don’t write SQL, or you want to save time on joins between tables.
You want a starting point and then adjust the query by hand.
You already have a query and want to change it with a short request, such as “include only invoiced orders”.

This applies to database cubes, which read their data through a SQL query. Spreadsheet, API and webhook cubes have no SQL query.

Before you start:

Have a database connection (SQL Server, PostgreSQL, MySQL and others) and a cube created from it.
Open the cube and wait for the Object Tree to load the tables, on the left of the editor.

Where it is

The stars button is in the query editor toolbar, on the right. Hover over it to see Generate SQL with AI. When you create a database cube with the new cube wizard, the same button shows up on the query step.

Query Editor tab of a database cube, with the Object Tree on the left, the SELECT TOP 1000 query in the editor and the toolbar with four buttons: stars, lightning, stop and brush

Toolbar button	What it does
Stars, Generate SQL with AI	Opens the SQL with AI generator.
Lightning, Execute Query	Runs the query. Shortcut `F5`.
Square, Cancel query execution	Cancels a running query.
Brush, Format Query	Tidies the SQL indentation. Shortcut `Ctrl` + `Shift` + `F`.

Generate the query

In the Cubes menu, open the database cube.
On the Query Editor tab, click the stars button, Generate SQL with AI.
Pick the tables the query should use. Click the field, type to search by name (Search tables...) and check each table. Pick up to 10.
Look at the Suggested prompts (AI). Click one to use it in the request.
In Describe your query, write what you want to see.
Click Generate Query or press Ctrl + Enter.
Review the SQL under Generated SQL. You can edit the text right there.
Click Apply to editor. The SQL goes into the editor in place of what was there.
Run the query with Execute Query and check the result.
Save the cube with Ctrl + S.

After saving, open the Field Mapping tab to choose the fields the query brought. See Cube fields.

Generator options

The window has two steps, Configurar (Configure) and Revisar (Review). Their names are fixed in Portuguese in the product and show at the top.

Option	What it does	Notes
Tables	Defines what the AI sees of the database.	From 1 to 10 tables. Tables and views sit in separate groups, with a VIEW tag on views. With no table picked, the generate button stays disabled.
Refine current SQL	Changes the SQL that is in the editor instead of writing a new one.	Only shows when the editor has SQL. You still need to pick tables. The window shows the start of the current SQL.
Suggested prompts (AI)	Example requests made by the AI from the picked tables and columns.	They show up after you pick tables, with a short delay. Clicking inserts the text into the request, and adds it on a new line if there is already text.
Describe your query	The request in natural language.	Required.
Generate Query	Sends the request and shows the SQL on the review step.	Shortcut `Ctrl` + `Enter`.
Back to prompt	Goes back to the request to adjust it and generate again.	The request and the tables stay filled in.
Apply to editor	Puts the SQL (with your edits) in the editor.	Replaces the text that was in the editor.

The request text, the picked tables and the refine option are kept in this browser, per cube (or per connection), so you can continue later.

What the AI receives

Your request.
From the picked objects: the name, the columns with each one’s type, the primary keys and the foreign keys (to suggest joins).
The database type (SQL Server, PostgreSQL and others), to write in the right dialect.
The current SQL, only when you turn on Refine current SQL.

The AI doesn’t receive the tables’ data rows. It only writes read queries (SELECT, with WITH when needed). Nothing runs until you run the query.

How to ask better

Say the period, the groupings and the totals you want to see.
Pick only the tables you need. Fewer tables make the answer more precise. Include the register tables (salesperson, customer) when you want names instead of codes.
Use the names shown in the object tree when you know them, such as “table pedidos, column data_pedido”.
Ask for columns with the cube in mind: a date, one or more categories (business unit, salesperson) and the numbers (revenue, cost). That is how the AI builds the result.
To adjust, turn on Refine current SQL and ask only for the change: “include only invoiced orders” or “also group by region”.

Example: revenue and cost by business unit

Aurora’s ERP has the tables dbo.pedidos and dbo.vendedores. Pick both and ask:

Revenue and cost by month and business unit in 2026, with the number of orders and the salesperson name

The AI returns a SELECT that joins the two tables by the salesperson code, filters 2026 and names the columns (receita, custo, vendedor). Run the query, check the numbers with someone from finance and save. Then create the Revenue and Cost measures on the new fields.

Limits and messages

Message	Cause and fix
No tables available. Please expand tables in the explorer to load the database structure.	The table list hasn’t loaded yet. Open the cube, wait for the Object Tree to load and try again.
Maximum number of tables reached (10)	Remove a table before picking another.
No suggestions yet. Check your connection or try changing the selected tables.	The suggestions didn’t come. You can still write the request by hand.
Error creating AI-generated query.	The generation failed. Try again in a moment.
Não foi possível carregar o esquema das tabelas selecionadas.	Hubviz couldn’t read the columns (this message is in Portuguese in the product). Test the connection under Data Sources.

The AI can be wrong. Check the SQL, run the query and validate the totals before building dashboards on top of it.
In the browser, tables and columns are read by the Hubviz servers, so the database must accept connections from the internet. See Databases.
The query replaces the editor’s SQL. If you want to keep the previous version, copy it before applying.

Next steps

Choose and adjust the fields the query brought in Cube fields.
Create the cube’s measures.
To generate a whole dashboard from a request, see Dashboard with AI.