Tutorial: cree un punto final NL2SQL en Postgres

Un punto final que recibe una pregunta en lenguaje natural, la transforma en una consulta SQL validada y limitada y luego devuelve el resultado. El motor nunca ejecuta SQL generado sin control: cada consulta pasa por una validación sintáctica antes de llegar a la base de datos.

La pregunta pasa por un LLM configurado (OpenAI, Anthropic (Claude) o Gemini, los tres proveedores nativos) que genera un SQL candidato. Este SQL nunca se ejecuta tal como está: pasa a través de un validador que analiza su árbol de sintaxis (sqlparser), solo permite consultas SELECT simples y agrega un LIMIT limitado si falta uno.

El validador rechaza explícitamente CTE/WITH, subconsultas, UNION, cláusulas de bloqueo (FOR UPDATE) y cualquier función fuera de una lista blanca (count, sum, avg, min, max, lower, upper, coalesce, date_trunc, now). Se admiten uniones de varias tablas.

Pregunta → LLM (OpenAI / Claude / Gemini) → validación AST (sqlparser) → LÍMITE limitado → ejecución SELECT

El diagrama consultado nunca es proporcionado por su solicitud: se introspecciona desde la base real del proyecto. Un campo schema, allowed_schema o schema_context enviado en el cuerpo de la solicitud se rechaza explícitamente (error 400) en lugar de ignorarse silenciosamente: el servidor decide por sí solo lo que realmente existe.

Con el SDK de JavaScript, el cliente de Aurabase expone aura.ai.nl2sql(). La firma es nl2sql(question, options): el esquema no forma parte de él, se introspecciona en el lado del servidor.

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

En HTTP sin formato, el punto final es POST /v1/ai/{project_id}/nl2sql, autenticado mediante la clave API del proyecto.

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

Pregunta enviada: "¿Cuántos pedidos realizaron este mes los clientes premium?". Esta es la forma del SQL realmente representado (los nombres de las tablas y las columnas dependen de su esquema):

{
  "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 si LIMIT proviene de la plantilla o fue agregado por el servidor. confidence es una heurística sobre la forma de la respuesta (bloque SQL bien formado o no), no una medida de corrección semántica del SQL generado. Una pregunta mal redactada devuelve un error explícito en lugar de un SQL alucinado: por ejemplo, si el SQL generado consulta una tabla que no está en su esquema, el mensaje nombra las tablas realmente disponibles.

Tres comprobaciones antes de la implementación: si el límite de filas (LIMIT) está adaptado a su volumen, si la función de Postgres utilizada por el motor permanece restringida al esquema del proyecto y si las tablas confidenciales tienen una política RLS activa: NL2SQL consulta la misma base de datos que el resto de su aplicación, no tiene derechos de acceso extendidos de forma predeterminada.

• El límite de línea predeterminado se puede configurar en el lado del servidor; un valor solicitado por encima del límite del servidor se niega explícitamente en lugar de reducirse silenciosamente.
• El validador bloquea el acceso al catálogo del sistema (pg_catalog, information_schema) y a los esquemas que no son del proyecto, independientemente de sus políticas RLS.
• RLS sigue siendo su última línea de defensa en tablas confidenciales: el validador limita la forma del SQL, no los derechos comerciales sobre los datos.

El motor es estrictamente legible: solo se aceptan solicitudes SELECT. Cualquier intento deINSERT, UPDATE, DELETE, DROP, CREATE o ALTER generado por la plantilla se rechaza antes de la ejecución; esta no es una convención de solicitud, es una regla impuesta en el nivel del árbol de sintaxis.

Otros límites estructurales: sin subconsultas, sin CTE/WITH, sin UNION y una lista blanca cerrada de diez funciones SQL. Una pregunta que naturalmente requiere una subconsulta (“clientes que nunca han realizado pedidos”) debe reformularse para que encaje en un SELECTsimple, o manejarse de manera diferente en el lado de la aplicación.

NL2SQL cubre preguntas estructuradas sobre sus datos relacionales. Para preguntas sobre contenido no estructurado (documentos, notas, tickets), el RAG nativo de Aurabase se basa en pgvector y una búsqueda HNSW. Ambas capacidades, y cómo combinarlas en un agente, se detallan en la página AI nativa en Postgres.