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:
- Rate limit 20 req/60 s per IP, fail-closed (managed cache down → deny).
- Workspace required (401 without a workspace).
- Entitlement
aiNarrative— available from the Pro plan up (403 below that). - Access check: the active workspace check — overdue payment/suspension blocks it (402/403).
- 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_liquidadapairs and theai.usagewith cost.