Tutorial: Erstellen Sie einen NL2SQL-Endpunkt auf Postgres

Ein Endpunkt, der eine Frage in natürlicher Sprache empfängt, diese in eine validierte und begrenzte SQL-Abfrage umwandelt und dann das Ergebnis zurückgibt. Die Engine führt generiertes SQL niemals unkontrolliert aus: Jede Abfrage durchläuft eine syntaktische Validierung, bevor sie die Datenbank erreicht.

Die Frage durchläuft ein konfiguriertes LLM – OpenAI, Anthropic (Claude) oder Gemini, die drei nativen Anbieter – das einen Kandidaten-SQL generiert. Dieses SQL wird niemals so ausgeführt, wie es ist: Es durchläuft einen Validator, der seinen Syntaxbaum (sqlparser) analysiert, nur einfache SELECT-Abfragen zulässt und ein begrenztes LIMIT hinzufügt, falls eines fehlt.

Der Validator lehnt explizit CTE/WITH, Unterabfragen, UNIONs, Sperrklauseln (FOR UPDATE) und alle Funktionen außerhalb einer Whitelist (count, sum, avg, min, max, lower, upper, coalesce, date_trunc, now). Multi-Table-Joins werden unterstützt.

Frage→LLM (OpenAI/Claude/Gemini)→AST-Validierung (SQLParser)→Begrenztes LIMIT→SELECT-Ausführung

Das abgefragte Diagramm wird niemals von Ihrer Anfrage bereitgestellt: Es wird von der tatsächlichen Basis des Projekts aus betrachtet. Ein im Anforderungstext gesendetes Feld schema, allowed_schema oder schema_context wird explizit abgelehnt (400-Fehler) und nicht stillschweigend ignoriert – der Server allein entscheidet, was tatsächlich vorhanden ist.

Mit dem JavaScript SDK macht der Aurabase-Client aura.ai.nl2sql()verfügbar. Die Signatur lautet nl2sql(question, options): Das Schema ist nicht Teil davon, es wird auf der Serverseite überprüft.

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 Raw-HTTP ist der Endpunkt POST /v1/ai/{project_id}/nl2sql, authentifiziert durch den Projekt-API-Schlüssel.

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
  }'

Gesendete Frage: „Wie viele Bestellungen wurden diesen Monat von Premium-Kunden aufgegeben?“. Hier ist die Form des tatsächlich gerenderten SQL (Tabellennamen und Spalten hängen von Ihrem Schema ab):

{
  "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 gibt an, ob LIMIT aus der Vorlage stammt oder vom Server hinzugefügt wurde. confidence ist eine Heuristik für die Form der Antwort (wohlgeformter SQL-Block oder nicht) – kein Maß für die semantische Korrektheit des generierten SQL. Eine schlecht formulierte Frage gibt eher einen expliziten Fehler als halluziniertes SQL zurück: Wenn das generierte SQL beispielsweise eine Tabelle abfragt, die nicht in Ihrem Schema enthalten ist, nennt die Meldung die tatsächlich verfügbaren Tabellen.

Drei Prüfungen vor der Bereitstellung: Ist die Zeilenobergrenze (LIMIT) an Ihr Volume angepasst, bleibt die von der Engine verwendete Postgres-Rolle auf das Projektschema beschränkt und verfügen die sensiblen Tabellen über eine aktive RLS-Richtlinie – NL2SQL fragt dieselbe Datenbank ab wie der Rest Ihrer Anwendung, sie verfügt standardmäßig nicht über erweiterte Zugriffsrechte.

• Die standardmäßige Leitungsobergrenze ist auf der Serverseite konfigurierbar; Ein angeforderter Wert über der Serverobergrenze wird explizit abgelehnt und nicht stillschweigend reduziert.
• Der Zugriff auf den Systemkatalog (pg_catalog, information_schema) und Nicht-Projektschemata wird vom Validator blockiert, unabhängig von Ihren RLS-Richtlinien.
• RLS bleibt Ihre letzte Verteidigungslinie bei sensiblen Tabellen: Der Validator begrenzt die Form der SQL, nicht die Geschäftsrechte an den Daten.

Die Engine ist streng lesbar: Es werden nur SELECT-Anfragen akzeptiert. Jeder von der Vorlage generierte Versuch,INSERT, UPDATE, DELETE, DROP, CREATE oder ALTER zu verwenden, wird vor der Ausführung abgelehnt. Hierbei handelt es sich nicht um eine Eingabeaufforderungskonvention, sondern um eine auf der Syntaxbaumebene auferlegte Regel.

Weitere strukturelle Einschränkungen: keine Unterabfragen, kein CTE/WITH, keine UNION und eine geschlossene Whitelist mit zehn SQL-Funktionen. Eine Frage, die natürlich eine Unterabfrage erfordert („Kunden, die noch nie bestellt haben“), muss umformuliert werden, damit sie in ein einfaches SELECTpasst, oder auf der Anwendungsseite anders gehandhabt werden.

NL2SQL behandelt strukturierte Fragen zu Ihren relationalen Daten. Bei Fragen zu unstrukturierten Inhalten (Dokumente, Notizen, Tickets) greift Aurabases natives RAG auf pgvector und eine HNSW-Suche zurück. Beide Funktionen – und wie man sie in einem Agent kombiniert – werden auf der Seite Native AI auf Postgresausführlich beschrieben.