Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-09-08

Prompting best practices (good × bad questions)

How to ask the text-to-SQL AI and the Q&A to get useful answers — with examples of good and bad questions.

On this page (7)

The quality of the AI's answer depends heavily on how you ask. This page gathers practical patterns for text-to-SQL (natural language → SQL) and for the dashboard Q&A (questions about the dashboard), with examples of good and bad questions.

Example workspace: Comércio Aurora Ltda (aurora).

The AI proposes, you confirm

Treat the AI as an assistant that proposes — you review and confirm.

The 5 principles#

  1. Be specific about the metric and the slice. Say which number, by which dimension, and for which period.
  2. Use the names from your model. "Revenue," "category," "branch" — the terms from your measures/columns help the grounding (see How the AI understands your data).
  3. One question at a time. Compound questions ("revenue and also margin and also why it dropped") are confusing; break them into steps.
  4. Ask for the period explicitly. "Last quarter," "2026," "last 30 days."
  5. Don't ask for a cause. The AI describes what the data shows; it does not claim that "X caused Y" (and it refuses when someone tries to force it).

Text-to-SQL: good × bad#

BadWhyGood
"show me everything"no metric or slice"total revenue by month in 2026"
"sales"ambiguous"quantity sold by category last quarter"
"which are the best?""best" at what?"top 10 products by revenue in July 2026"
"compare with the market"data you don't have"this year's revenue vs last year by branch"

Note

If the question is ambiguous and there's a published semantic model, the AI refuses before spending tokens and lists the options ("did you mean Gross revenue or Net revenue?"). Pick one and ask again — it's cheaper and more accurate.

Dashboard Q&A: good × bad#

The Q&A answers only based on the already materialized snapshot, and every statement comes with a verifiable citation. So:

BadWhyGood
"why did sales drop?"asks for a cause"which category dropped the most vs the previous month on this dashboard?"
"what's the forecast for December?"not in the snapshot"which customer had the highest revenue in the period shown?"
"is this good?"opinion with no basis"which items are below the target shown?"
"what was the total?" (on a visual that is a sample)a sample doesn't allow a totalaggregate in text-to-SQL for the exact total

Read the answer correctly#

  • Text-to-SQL returns read-only SQL + an explanation + an estimated cost. Review the SQL (a column/table name may be wrong) before trusting it. There's self-correction (one retry with the real error from the datalake), but it's not a guarantee.
  • Q&A includes citations that point to the data backing each sentence. If the answer comes back as a refusal (sem_evidencia, fora_do_contexto), it's because there was no backing — don't force it.
  • On a sample, the AI is forbidden from stating a total/sum/"largest"/"all."

When the AI refuses (and why that's good)#

A refusal isn't a failure — it's honesty. The common refusals:

  • Ambiguity → pick one of the options and ask again.
  • Out of context → the question doesn't touch any term on the dashboard; rephrase using the names from the model.
  • No evidence → the dashboard doesn't support the statement; aggregate in SQL or change the question.

Common mistakes#

  • Asking the Q&A for real time: it reads the snapshot from the last refresh, not "now."
  • Treating the explanation as proven fact: insights and recommendations are hypotheses to investigate — see Insights.
  • Pasting secrets/PII into the question: don't. The text goes to the provider (fenced, but it still leaves) — ask about structure and numbers, not about personal data.

Related#


Last reviewed: 2026-09-08.

Related links