Öğretici: Postgres'te NL2SQL uç noktası oluşturma

Doğal dil sorusunu alan bir uç nokta, bunu doğrulanmış ve sınırlanmış bir SQL sorgusuna dönüştürür ve ardından sonucu döndürür. Motor, oluşturulan SQL'i hiçbir zaman kontrol olmadan yürütmez: her sorgu, veritabanına ulaşmadan önce sözdizimsel doğrulamadan geçer.

Soru, aday bir SQL oluşturan yapılandırılmış bir LLM (OpenAI, Anthropic (Claude) veya Gemini, üç yerel sağlayıcı) üzerinden geçiyor. Bu SQL hiçbir zaman olduğu gibi yürütülmez: sözdizimi ağacını (sqlparser) ayrıştıran bir doğrulayıcıdan geçer, yalnızca basit SELECT sorgularına izin verir ve eğer eksikse sınırlı bir LIMIT ekler.

Doğrulayıcı, CTE/WITH'yi, alt sorguları, UNION'ları, kilitleme cümlelerini (FOR UPDATE) ve beyaz listenin dışındaki tüm işlevleri (count, sum, avg, min, max, lower, upper, açıkça reddeder) coalesce, date_trunc, now). Çoklu tablo birleştirmeleri desteklenir.

Soru→LLM (OpenAI/Claude/Gemini)→AST doğrulama (sqlparser)→Sınırlı LIMIT→SELECT yürütme

Sorgulanan diyagram hiçbir zaman isteğiniz üzerine sağlanmaz: projenin gerçek tabanından iç gözlem yapılır. İstek gövdesinde gönderilen bir schema, allowed_schema veya schema_context alanı sessizce göz ardı edilmek yerine açıkça reddedilir (400 hata) - gerçekte neyin var olduğuna sunucu tek başına karar verir.

Aurabase istemcisi, JavaScript SDK'sı ile aura.ai.nl2sql()'yi kullanıma sunar. İmza nl2sql(question, options): şema onun bir parçası değil, sunucu tarafında inceleniyor.

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

Ham HTTP'de uç nokta, proje API anahtarıyla kimliği doğrulanan POST /v1/ai/{project_id}/nl2sql'dir.

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

Gönderilen soru: "Bu ay premium müşteriler tarafından kaç sipariş verildi?". Gerçekte oluşturulan SQL'in biçimi şöyledir (tablo adları ve sütunlar şemanıza bağlıdır):

{
  "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, LIMIT öğesinin şablondan mı geldiğini yoksa sunucu tarafından mı eklendiğini belirtir. confidence yanıt biçimindeki bir buluşsal yöntemdir (iyi biçimlendirilmiş SQL bloğu olsun veya olmasın) - oluşturulan SQL'in anlamsal doğruluğunun bir ölçüsü değildir. Kötü ifade edilmiş bir soru, halüsinasyonlu SQL yerine açık bir hata döndürür: örneğin, oluşturulan SQL şemanızda olmayan bir tabloyu sorgularsa, mesaj gerçekte mevcut tabloların adlarını verir.

Dağıtımdan önce üç kontrol: satır tavanı (LIMIT) biriminize uyarlandı mı, motor tarafından kullanılan Postgres rolü proje şemasıyla sınırlı mı kaldı ve hassas tabloların etkin bir RLS politikası var mı — NL2SQL, uygulamanızın geri kalanıyla aynı veritabanını sorgular, varsayılan olarak genişletilmiş erişim haklarına sahip değildir.

• Varsayılan satır sınırı sunucu tarafında yapılandırılabilir; sunucu sınırının üzerinde talep edilen bir değer, sessizce düşürülmek yerine açıkça reddedilir.
• Sistem kataloğuna (pg_catalog, information_schema) ve proje dışı şemalara erişim, RLS politikalarınızdan bağımsız olarak doğrulayıcı tarafından engellenir.
• RLS, hassas tablolardaki son savunma hattınız olmaya devam ediyor: doğrulayıcı, veriler üzerindeki iş haklarını değil, SQL'in biçimini sınırlar.

Motor kesinlikle okunabilir niteliktedir: yalnızca SELECT istekleri kabul edilir. Şablon tarafından oluşturulanINSERT, UPDATE, DELETE, DROP, CREATE veya ALTER girişimleri yürütülmeden önce reddedilir - bu bir bilgi istemi kuralı değildir, sözdizimi ağacı düzeyinde uygulanan bir kuraldır.

Diğer yapısal sınırlar: alt sorgu yok, CTE/WITH yok, UNION yok ve on SQL işlevinden oluşan kapalı beyaz liste. Doğal olarak bir alt sorgu gerektiren bir soru ("hiç sipariş vermemiş müşteriler"), basit bir SELECTiçine sığacak şekilde yeniden formüle edilmeli veya uygulama tarafında farklı şekilde ele alınmalıdır.

NL2SQL covers structured questions about your relational data. For questions about unstructured content (documents, notes, tickets), Aurabase's native RAG relies on pgvector and an HNSW search. Both capabilities — and how to combine them in an agent — are detailed on the Native AI on Postgres page.