Tutorial: crea un endpoint NL2SQL su Postgres

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.

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.

Con JavaScript SDK, 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
  }'

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.

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 esegue query sullo 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 dai criteri 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.

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 SELECTo gestita in modo diverso dal lato dell'applicazione.

NL2SQL copre domande strutturate sui tuoi dati relazionali. Per domande su contenuti non strutturati (documenti, note, ticket), il RAG nativo di Aurabase si affida a pgvector e ad una ricerca HNSW. Entrambe le funzionalità, e come combinarle in un agente, sono descritte in dettaglio nella pagina Native AI su Postgres.