SIQL — NL-to-SQL

SIQL's NL-to-SQL turns a question written in plain Portuguese into a valid SELECT over the right lakehouse tables, anchored in the platform's ontology and knowledge graph. Writing SQL against a lakehouse you do not know by heart means opening the catalog, guessing table names and hoping. Here you type "mostre transações suspeitas em 2024" and get the SQL ready — with governance rails built in: read-only, always limited, restricted to the resolved semantic scope and never executed automatically. You review, copy and decide.

Where it lives: the NL-to-SQL tab in Descobrir›Intelligent Query Layer. Requires the SIQL:ADMIN permission.

How it works

The path from question to SQL, in nine steps:

1. The question is broken into relevant terms (stopwords are discarded).
2. Each term is matched against the ontology concepts — only matches scoring 0.6 or above are kept.
3. The concepts resolve, in the semantic graph, the in-scope tables; the union of all of them forms the "Tabelas Resolvidas" (resolved tables) list.
4. The language model receives the question together with that closed list — and may only use the tables in it.
5. The answer comes back structured, carrying the SQL, the confidence, the explanation and the tables actually referenced.
6. The SQL goes through read-only validation — any write command, DDL or multiple statements in the same answer is rejected.
7. A LIMIT is injected or clamped to the configured ceiling.
8. The platform checks that the referenced tables are contained in the resolved tables; anything outside that gets discarded.
9. The generation is recorded in the audit trail.

At no point does the system execute the SQL — you copy and paste it wherever you want.

Safety rails

1. Read-only — INSERT, UPDATE, DELETE, DROP, ALTER, MERGE, TRUNCATE, CREATE, GRANT, REVOKE, REPLACE, UPSERT, LOAD, COPY, EXECUTE, EXEC and CALL are rejected, as is any answer with more than one statement.
2. Hard limit — LIMIT is always present; the ceiling is configurable in datta.siql.semantic.nl-to-sql.max-limit (default 10,000 rows).
3. Closed scope — if the SQL references a table outside the resolved list, the answer is rejected and flagged as degraded (degraded=true).
4. Usage limit — 30 generations per hour per user, enforced by a distributed counter with an in-memory fallback.
5. Exhaustive auditing — the SIQL.NL_TO_SQL_* events cover generated, rejected, answer-parsing failure, degraded model, out-of-scope, usage-limit block and no tables resolved.
6. Privacy — the prompt does not include user data, only the question and the schema/ontology. Any personal data appearing in the explanation is masked before being displayed.

Using the NL-to-SQL tab

1. Open Descobrir›Intelligent Query Layer and click the NL-to-SQL tab.
2. Type the question in the text field — for example, "top 10 processos por valor".
3. Click Gerar SQL.
4. The result appears with the SQL highlighted and pills showing the confidence, the estimated cost and the resolved entities:

SELECT * FROM hive.public.processos ORDER BY valor DESC LIMIT 10

1. Review it. If it looks right, click Copiar SQL — the SQL goes to the clipboard and is not executed by the screen.
2. Run it in whichever client you prefer (Trino, DATTAX), when and how you want.

The generated SQL is in the Trino 480 dialect.

What to expect from the result

The accuracy target is at least 75% on a set of 20 questions representative of the domain. Across the five examples above, the observed accuracy was 4 out of 5 (80%) — counting the last one's block as the correct behavior. That is exactly why human review is part of the flow: the confidence and the explanation are displayed to support your decision.

Troubleshooting

Generation is also available through the API for administrative integrations, with the same permission and the same limit of 30 calls per hour — see the API reference.