Il motore NL2SQL di Aurabase fa parte dell'intelligenza artificiale nativa diintegrata nel backend: non è un servizio di terze parti da mettere insieme. Prerequisiti per seguire questa guida: un progetto Aurabase esistente, uno schema di database semplice per l'esempio e una chiave API del progetto.
Cosa costruirai
Un endpoint che riceve una domanda in linguaggio naturale, la trasforma in una query SQL convalidata e delimitata, quindi restituisce il risultato. Il motore non esegue mai l'SQL generato senza controllo: ogni query passa attraverso la validazione sintattica prima di raggiungere il database.
Questo tutorial utilizza @aurabase/aurabase-js JavaScript SDK e la chiamata HTTP non elaborata equivalente, quindi puoi seguire da qualsiasi lingua.
Come funziona il motore NL2SQL
La domanda passa attraverso un LLM configurato – OpenAI, Anthropic (Claude) o Gemini, i tre fornitori nativi – che genera un SQL candidato. Questo SQL non viene mai eseguito così com'è: passa attraverso un validatore che ne analizza l'albero della sintassi (sqlparser), consente solo semplici query SELECT e aggiunge un LIMIT limitato se ne manca uno.
Il validatore rifiuta esplicitamente CTE/WITH, sottoquery, UNION, clausole di blocco (FOR UPDATE) e qualsiasi funzione esterna a una whitelist (count, sum, avg, min, max, lower, upper, coalesce, date_trunc, now). Sono supportate le unioni di più tabelle.
Domanda→LLM (OpenAI/Claude/Gemini)→ convalida AST (sqlparser)→LIMITE delimitato→esecuzione SELECT
Lo schema interrogato non viene mai fornito dalla vostra richiesta: viene introspezionato dalla base reale del progetto. Un campo schema, allowed_schema o schema_context inviato nel corpo della richiesta viene esplicitamente rifiutato (errore 400) anziché ignorato silenziosamente: solo il server decide cosa esiste effettivamente.
Configura l'endpoint NL2SQL
Con l'SDK JavaScript, il client Aurabase espone aura.ai.nl2sql(). La firma è nl2sql(question, options): lo schema non ne fa parte, viene introspezionato lato server.
import { aura } from '@/lib/aurabase'
export async function POST(req: Request) {
const { question } = await req.json()
const { data, error } = await aura.ai.nl2sql(
question,
{ limit: 50 }
)
if (error) return Response.json({ error }, { status: 400 })
return Response.json(data)
}
In HTTP non elaborato, l'endpoint è POST /v1/ai/{project_id}/nl2sql, autenticato dalla chiave API del progetto.
curl -X POST https://<votre-gateway>/v1/ai/<project_id>/nl2sql \
-H "apikey: <votre-cle-api>" \
-H "Content-Type: application/json" \
-d '{
"question": "Combien de commandes ont été passées ce mois-ci par des clients premium ?",
"limit": 50
}'
Non inviare schema, né allowed_schema, né schema_context nel corpo della richiesta: lo schema interrogato è determinato dal server, questi campi vengono esplicitamente rifiutati (400) anziché sovrascritti silenziosamente.
Prova con una vera domanda in francese
Domanda inviata: “Quanti ordini sono stati effettuati questo mese da clienti premium?”. Ecco la forma dell'SQL effettivamente reso (i nomi delle tabelle e le colonne dipendono dallo schema):
{
"data": {
"sql": "SELECT count(*) FROM orders WHERE customer_plan = 'premium' AND created_at >= date_trunc('month', now()) LIMIT 50",
"explanation": "Compte les commandes de ce mois pour les clients premium.",
"confidence": 0.85,
"tables": ["orders"],
"columns": ["customer_plan", "created_at"],
"limit": 50,
"limit_injected": false
},
"meta": null
}
limit_injected indica se LIMIT proviene dal modello o è stato aggiunto dal server. confidence è un'euristica sulla forma della risposta (blocco SQL ben formato o meno) - non una misura della correttezza semantica dell'SQL generato. Una domanda mal formulata restituisce un errore esplicito anziché un SQL allucinato: ad esempio, se l'SQL generato interroga una tabella non presente nel tuo schema, il messaggio nomina le tabelle effettivamente disponibili.
Produzione sicura
Tre controlli prima della distribuzione: il limite massimo delle righe (LIMIT) è adatto al tuo volume, il ruolo Postgres utilizzato dal motore rimane limitato allo schema del progetto e le tabelle sensibili hanno una politica RLS attiva — NL2SQL interroga lo stesso database del resto dell'applicazione, non dispone di diritti di accesso estesi per impostazione predefinita.
- Il limite di riga predefinito è configurabile sul lato server; un valore richiesto superiore al limite del server viene negato esplicitamente anziché ridotto silenziosamente.
- L'accesso al catalogo di sistema (
pg_catalog,information_schema) e agli schemi non di progetto è bloccato dal validatore, indipendentemente dalle policy RLS. - RLS rimane la tua ultima linea di difesa sulle tabelle sensibili: il validatore limita la forma dell'SQL, non i diritti commerciali sui dati.
Limiti attuali di cui essere consapevoli
Il motore è rigorosamente leggibile: vengono accettate solo le richieste SELECT. Qualsiasi tentativo diINSERT, UPDATE, DELETE, DROP, CREATE o ALTER generato dal modello viene rifiutato prima dell'esecuzione: questa non è una convenzione di prompt, è una regola imposta a livello dell'albero della sintassi.
Altri limiti strutturali: nessuna sottoquery, nessuna CTE/WITH, nessuna UNION e una whitelist chiusa di dieci funzioni SQL. Una domanda che richiede naturalmente una sottoquery ("clienti che non hanno mai ordinato") deve essere riformulata per adattarsi a un semplice SELECT o gestita in modo diverso dal lato dell'applicazione.
RAG e agenti
NL2SQL copre domande strutturate sui tuoi dati relazionali. Per domande sul contenuto non strutturato (documenti, note, ticket), il RAG nativo di Aurabase si basa su pgvector e su una ricerca HNSW. Entrambe le funzionalità, e come combinarle in un agente, sono dettagliate nella pagina AI nativa sulla pagina Postgres.