Skip to content

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

Updated on 2026-10-04

Natural language query

Write your question in plain language and get a ready-made query over your tables.

On this page (9)

Engine: Uses LLM (Anthropic)


1. What it does

You describe in plain language what you want to see ("revenue by month for the last year") and the AI proposes a read-only SQL query for your datalake, with an explanation in plain language and a cost/bytes estimate.

2. Deterministic or LLM?

LLM. The model is resolved like this:

  • The model provider is configured by us in the environment; you are never asked for an AI credential.
  • When there is no direct credential, access to the model goes through a managed gateway (anthropic/claude-sonnet-5).
  • With no provider at all, in dev/preview it falls back to a deterministic mock generator (a simple heuristic that matches terms in the question with the schema). In production, with no provider, the route responds 503 instead of faking a result (production guard).

3. Data sent and egress

The following goes to the LLM, inside an untrusted-data fence (<dados id="...">):

  • Your catalog schema — names of tables and columns from the silver and gold layers of your workspace. Columns flagged as PII are excluded before the prompt is built — the AI does not even know they exist.
  • Your question, fenced as <dados id="pergunta">.
  • On the semantic path (when there is a published semantic model), the model is sent (ids of tables/relationships/measures) instead of the raw columns.

No data rows are sent. Text-to-SQL sends only structure (schema/model), never the contents of the tables. A workspace guard discards any table whose name does not start with your workspace prefix, even if the catalog were corrupted.

4. Privacy and retention

  • Catalog PII does not leave (excluded at the source, before the prompt is built).
  • All customer text (question, table names) goes in fenced, with fence tokens neutralized — this is the defense against prompt injection (covered by an adversarial suite).
  • Usage (model, tokens, cost in R$, egress summary: number of schema tables, 0 rows) is recorded in the audit log with the action ai.usage, scoped by workspace.

5. Tokens, cost and budget

  • Before the call, the product reserves the estimated budget (ai.reserva) and only then checks the cap (reserve-then-verify pattern — concurrency does not break the cap). After the call, it settles with the real cost (ai.usage + ai.reserva_liquidada).
  • Monthly cap per workspace (default R$ 50/month; no cap when set to zero = no cap). Exceeded → the call is refused with a clear message and recorded in ai.blocked.
  • Cost guard for the query itself: a bytes/cost estimate via a real dry-run on the datalake, and the query is validated before it runs.
  • Details in Privacy, external sending, budget and shutdown.

6. How to turn it on, who can use it and how to turn it off

The POST /api/ai/sql route only calls the provider after passing, in this order:

  1. Rate limit 20 req/60 s per IP, fail-closed (managed cache down → deny).
  2. Workspace required (401 without a workspace).
  3. Entitlement aiNarrative — available from the Pro plan up (403 below that).
  4. Access check: the active workspace check — overdue payment/suspension blocks it (402/403).
  5. Capability check for natural language query — a kill switch independent of billing.

General shutdown: sending to model providers can be turned off in the environment; in that state no LLM call happens, even with a credential configured — text-to-SQL falls back to the deterministic mock and nothing leaves the product.

7. Refusals

The AI does not make things up:

  • Ambiguity (semantic path): if a term in the question matches ≥2 measures/columns, it refuses before spending tokens, listing the options ("which one did you mean?").
  • Invalid ids (semantic path): if the answer cites an identifier that does not exist in the published model, the query is discarded (ungrounded SQL does not come out) — the cost of the tokens already spent is settled honestly.
  • Cap reached → 429 with a message, without spending.

8. Limitations and absence of causality

  • Generates only SELECT (no DML/DDL). Even so, review it before trusting it: the AI may get a column/table name wrong — that is why there is self-correction (one retry with the real error from the datalake), but it is not a guarantee.
  • The explanation describes what the query does; it does not claim cause-and-effect relationships in your data.
  • In demo mode (no provider), the SQL comes from a simple heuristic — it is useful for experimenting, not for production.

9. How to validate

  • Shutdown: with sending to providers turned off, confirm that the answer comes from the deterministic result (the explanation says "demo mode") and that no external call happens.
  • PII out of the prompt: flag a column as PII in the catalog and check that it does not appear in the schema sent to the AI.
  • Anti-injection: write text in the question that tries to "close" the fence and give orders to the AI, and confirm that it treats it as data, not as instructions.
  • Refusal due to ambiguity/ids: with a published semantic model, ask an ambiguous question and check the refusal (no SQL).
  • Budget: check the workspace audit log for the ai.reserva/ai.reserva_liquidada pairs and the ai.usage with cost.

Related links