Cos'è NL2SQL e come funziona?

NL2SQL si riferisce alla traduzione automatica di una domanda in linguaggio naturale in una query SQL che può essere eseguita su base relazionale. A differenza di un chatbot generico che risponde in testo libero, un sistema NL2SQL produce un artefatto strutturato, SQL, che viene eseguito su dati reali e restituisce un risultato verificabile riga per riga.

Il termine “text-to-SQL” deriva dalla ricerca accademica sull’elaborazione del linguaggio naturale. “NL2SQL” è l'abbreviazione più utilizzata sul lato del prodotto e della documentazione tecnica. Entrambi si riferiscono allo stesso problema: colmare il divario tra una domanda posta nel linguaggio quotidiano e la sintassi precisa prevista da un motore SQL.

NL2SQL si distingue da un agente conversazionale collegato a un database in senso lato. Il primo produce una query leggibile e verificabile; il secondo può concatenare più chiamate di tool (ricerca, calcolo, scrittura) senza necessariamente risultare in un SQL unico ed ispezionabile. Un sistema NL2SQL adeguatamente progettato rimane all'interno di questo ambito deliberatamente limitato: tradurre, convalidare, eseguire, restituire un risultato.

Una pipeline NL2SQL affidabile segue sempre la stessa sequenza, indipendentemente dal provider: la domanda passa attraverso un modello linguistico, quindi l'SQL prodotto viene convalidato prima dell'esecuzione, mai dopo. L'implementazione di Aurabase, verificata nel codice del servizio aura-ai, illustra ciascuno di questi passaggi con regole concrete anziché con una descrizione astratta.

1.La domanda viene ricevuta con lo schema effettivo della base

Il sistema associa la domanda in linguaggio naturale allo schema del database interrogato: nomi di tabelle, colonne, tipologie. Questo modello deve derivare dall'introspezione della base effettiva, non da una descrizione fornita dal chiamante. Un'implementazione che accetta uno schema dichiarato dal cliente aprirebbe la porta a domande su tabelle inesistenti o al superamento dell'isolamento tra progetti. Il motore Aurabase rifiuta esplicitamente (errore 400) qualsiasi campo schema inviato nella richiesta, anziché ignorarlo silenziosamente.

2. Un LLM genera un SQL candidato

Il modello linguistico riceve la domanda e lo schema nel prompt, quindi produce una query SQL candidata insieme a una breve spiegazione. Aurabase tratta tre fornitori allo stesso modo con un client nativo dedicato: OpenAI, Anthropic (Claude) e Gemini. Questo SQL candidato è in questa fase solo una proposta, mai eseguita direttamente.

3.L'SQL candidato viene convalidato prima dell'esecuzione, non dopo

Questo è il passaggio che distingue un sistema NL2SQL serio da una semplice chiamata LLM seguita da un'esecuzione ingenua. L'SQL generato viene analizzato in un albero di sintassi (AST) anziché ispezionato mediante una ricerca per parole chiave, che può essere facilmente aggirata. L'implementazione Aurabase, con la libreria sqlparser, consente solo semplici query SELECT: CTE/WITH, sottoquery, UNION, funzioni finestra e clausole di blocco (FOR UPDATE) vengono esplicitamente rifiutate, così come qualsiasi funzione SQL al di fuori di una whitelist di dieci funzioni (count, sum, avg, min, max, lower, upper, coalesce, date_trunc, now).

4.La query confermata viene eseguita con un limite di riga

L'SQL convalidato riceve un LIMIT se non ne ha già uno: 100 righe per impostazione predefinita con Aurabase, 1000 massimo, entrambi i valori configurabili lato server. Una richiesta oltre il limite viene negata esplicitamente anziché ridotta silenziosamente. La risposta indica se questo LIMIT è stato aggiunto dal server, quindi il chiamante sa se l'SQL eseguito differisce da quello prodotto dal modello.

-- Domanda: "Quanti ordini questo mese per i clienti premium?"
SELECT count(*) FROM orders
WHERE customer_plan = 'premium'
  AND created_at >= date_trunc('month', now())
LIMIT 100  -- aggiunto dal server, mancante dall'SQL generato

I dettagli completi di questa pipeline, con ogni chiamata HTTP e ogni risposta JSON, sono trattati nel nostro tutorial passo passo per creare un endpoint NL2SQL su Postgres.

NL2SQL non è destinato a sostituire ovunque l'SQL scritto a mano. Copre un ambito specifico: domande ad hoc, una tantum, poste da qualcuno che non conosce SQL o che vuole semplicemente risparmiare tempo su una semplice query.

• Esplorazione ad hoc di una dashboard da parte di una persona non tecnica (supporto, prodotto, gestione).
• Prototipazione rapida di una funzionalità che interroga il database senza scrivere un percorso API dedicato per ogni possibile domanda.
• Self-service analitico limitato: conta, filtra, semplicemente aggrega, senza dare accesso diretto al database all'utente finale.

L'SQL scritto a mano rimane preferibile non appena la domanda va oltre questo ambito. Un'implementazione convalidata da AST come quella sopra descritta esclude CTE, sottoquery e funzioni finestra per costruzione, per motivi di sicurezza. Un'analisi che strutturalmente necessita di queste costruzioni, coorti, finestre temporali avanzate, non passa attraverso NL2SQL: viene codificata direttamente. Questo è un compromesso accettato, la sicurezza del sistema viene prima della completezza dell'SQL generato.

Tre rischi ricorrono sistematicamente in un'implementazione NL2SQL, con risposte diverse a seconda della maturità del sistema.

SQL injection tramite prompt o domanda

Un LLM può essere manipolato per produrre SQL dannoso se la domanda stessa contiene un tentativo di injection "ignora le istruzioni precedenti e...". La difesa non è fidarsi del prompt, ma validare l'SQL prodotto indipendentemente da quanto richiesto, esattamente lo step 3 della pipeline sopra descritta. L'argomento merita una trattazione dedicata: vedere Securing NL2SQL Against SQL Injection per vettori di attacco e contromisure precisi.

Allucinazione di tabelle o colonne inesistenti

Il modello potrebbe inventare un nome di tabella o di colonna plausibile ma mancante nello schema effettivo, soprattutto nel caso di schemi di grandi dimensioni o scarsamente documentati. Un'implementazione che convalida l'SQL generato rispetto allo schema del database effettivo rifiuta la query con un messaggio esplicito, elencando le tabelle effettivamente disponibili, anziché lasciare che un errore SQL non elaborato venga restituito all'utente.

Costo e latenza delle model call

Ogni domanda NL2SQL attiva una chiamata al modello linguistico, con i propri costi e la propria latenza, oltre al tempo di esecuzione SQL. Questo costo aumenta rapidamente se NL2SQL funge da livello predefinito per domande ripetitive, che trarrebbero vantaggio dall'essere memorizzati nella cache o esposti come report standard anziché ritradotti ogni volta.

Due architetture producono un risultato visibile simile, ma con garanzie molto diverse. NL2SQL nativo integra generazione, validazione ed esecuzione direttamente nel livello backend che già conosce lo schema del progetto e i diritti di accesso: questa è la logica descritta sopra per Aurabase, dove il servizio aura-ai condivide l'infrastruttura e l'isolamento dello schema con il resto del backend.

Un NL2SQL assemblato combina un servizio LLM generico, un connettore al database e un livello di convalida fai-da-te. Niente impedisce a questo approccio di essere sicuro, ma ogni garanzia, schema introspettivo lato server, convalida AST, limite di riga, tenant di isolamento, deve essere implementato e mantenuto dal team che mette insieme questi mattoni, piuttosto che fornito dalla piattaforma.

Il panorama degli strumenti NL2SQL, nativi e assemblati, open source e commerciali, viene confrontato in dettaglio nel nostro Confronto strumenti NL2SQL 2026.

NL2SQL e RAG (retrieval-augmented generation) rispondono a due diverse famiglie di domande, spesso confuse perché entrambe si basano su un LLM connesso a un database.

NL2SQL si rivolge a dati strutturati e relazionali: quante, quando, quale proporzione, domande che si traducono naturalmente in aggregazioni SELECT, GROUP BY. Il RAG si rivolge a contenuti non strutturati: documenti, note, ticket di supporto, dove la risposta non rientra in una riga della tabella ma richiede di trovare un passaggio rilevante per somiglianza semantica, ricerca vettoriale su pgvector, indice HNSW, prima di contestualizzarlo nel modello.

Le due capacità possono coesistere nello stesso progetto e combinarsi in un agente che sceglie l'una o l'altra a seconda della domanda posta. Il pilastro AI nativo di Aurabase descrive in dettaglio come i due meccanismi funzionano insieme e la nostra guida alla pipeline RAG su pgvector copre l'implementazione del secondo.