Aurabase's NL2SQL engine is part of thenative AI integrated into the backend: not a third-party service to put together. Prerequisites to follow this guide: an existing Aurabase project, a simple database schema for the example, and a project API key.
Ne inşa edeceksin
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 asla kontrol olmadan yürütmez: her sorgu, veritabanına ulaşmadan önce sözdizimsel doğrulamadan geçer.
Bu eğitimde @aurabase/aurabase-js JavaScript SDK'sı ve eşdeğer ham HTTP çağrısı kullanılır, böylece herhangi bir dilden takip edebilirsiniz.
NL2SQL motoru nasıl çalışır?
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.
NL2SQL uç noktasını yapılandırma
JavaScript SDK'sı ile Aurabase istemcisi aura.ai.nl2sql() öğesini 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
}'
İsteğin gövdesinde schema, allowed_schema veya schema_context göndermeyin: sorgulanan şema sunucu tarafından belirlenir, bu alanlar sessizce üzerine yazılmak yerine açıkça reddedilir (400).
Fransızca gerçek bir soruyla test edin
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.
Güvenli üretim
Dağıtımdan önce üç kontrol: satır tavanı (LIMIT) biriminize uyarlanmış mı, motor tarafından kullanılan Postgres rolü proje şemasıyla sınırlı mı kalıyor ve hassas tabloların etkin bir RLS politikası var mı — NL2SQL uygulamanızın geri kalanıyla aynı veritabanını sorguluyor, varsayılan olarak genişletilmiş erişim haklarına sahip değil.
- 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ıza bakılmaksızın 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.
Dikkat edilmesi gereken mevcut 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 SELECT içine sığacak şekilde yeniden formüle edilmeli veya uygulama tarafında farklı şekilde ele alınmalıdır.
RAG ve ajanlar
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.