البرنامج التعليمي: إنشاء نقطة نهاية NL2SQL على Postgres

نقطة نهاية تتلقى سؤالاً باللغة الطبيعية، وتحوله إلى استعلام SQL محدد ومتحقق من صحته، ثم تقوم بإرجاع النتيجة. لا يقوم المحرك أبدًا بتنفيذ SQL الذي تم إنشاؤه بدون تحكم: كل استعلام يمر عبر التحقق النحوي قبل الوصول إلى قاعدة البيانات.

يمر السؤال من خلال LLM مهيأ - OpenAI، أو Anthropic (Claude) أو Gemini، المزودين الأصليين الثلاثة - والذي يقوم بإنشاء SQL مرشح. لا يتم تنفيذ SQL هذا أبدًا كما هو: فهو يمر عبر أداة التحقق التي توزع شجرة بناء الجملة الخاصة بها (sqlparser)، وتسمح فقط باستعلامات SELECT البسيطة، وتضيف LIMIT محدودة إذا كان أحدها مفقودًا.

يرفض المدقق صراحةً CTE/WITH والاستعلامات الفرعية والاتحادات وعبارات القفل (FOR UPDATE) وأي وظيفة خارج القائمة البيضاء (count, sum, avg, min, max, lower, upper, coalesce، date_trunc، now). يتم دعم عمليات الانضمام للجداول المتعددة.

سؤال ← LLM (OpenAI/Claude/Gemini) ← التحقق من صحة AST (sqlparser) ← Bounded LIMIT ← تنفيذ SELECT

لا يتم توفير المخطط الذي تم الاستعلام عنه أبدًا من خلال طلبك: فهو يتم استبطانه من القاعدة الحقيقية للمشروع. يتم رفض الحقل schemaأو allowed_schema أو schema_context المرسل في نص الطلب بشكل صريح (خطأ 400) بدلاً من تجاهله بصمت - الخادم وحده هو الذي يقرر ما هو موجود بالفعل.

باستخدام JavaScript SDK، يكشف عميل Aurabase عن aura.ai.nl2sql(). التوقيع هو nl2sql(question, options): المخطط ليس جزءًا منه، بل يتم استبطانه من جانب الخادم.

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

في HTTP الخام، نقطة النهاية هي POST /v1/ai/{project_id}/nl2sql، والتي تمت مصادقتها بواسطة مفتاح واجهة برمجة تطبيقات المشروع.

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

تم إرسال السؤال: "كم عدد الطلبات التي تم تقديمها هذا الشهر من قبل العملاء المميزين؟". فيما يلي نموذج SQL الذي تم تقديمه بالفعل (تعتمد أسماء الجداول والأعمدة على مخططك):

{
  "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 يأتي من القالب أو تمت إضافته بواسطة الخادم. confidence هو إرشادي لشكل الاستجابة (كتلة SQL جيدة التكوين أم لا) - وليس مقياسًا للصحة الدلالية لـ SQL التي تم إنشاؤها. يُرجع السؤال ذو الصياغة السيئة خطأً صريحًا بدلاً من SQL المهووس: على سبيل المثال، إذا كان SQL الذي تم إنشاؤه يستعلم عن جدول غير موجود في المخطط الخاص بك، فستقوم الرسالة بتسمية الجداول المتوفرة بالفعل.

ثلاث عمليات تحقق قبل النشر: هل سقف الصف (LIMIT) متكيف مع وحدة التخزين الخاصة بك، وهل يظل دور Postgres الذي يستخدمه المحرك مقيدًا بمخطط المشروع، وهل تحتوي الجداول الحساسة على سياسة RLS نشطة - يستعلم NL2SQL عن نفس قاعدة البيانات مثل بقية التطبيق الخاص بك، وليس لديه حقوق وصول موسعة بشكل افتراضي.

• الحد الأقصى للخط الافتراضي قابل للتكوين من جانب الخادم؛ يتم رفض القيمة المطلوبة أعلى من الحد الأقصى للخادم بشكل صريح بدلاً من تقليلها بصمت.
• تم حظر الوصول إلى كتالوج النظام (pg_catalog, information_schema) والمخططات غير المتعلقة بالمشروع بواسطة أداة التحقق، بغض النظر عن سياسات RLS الخاصة بك.
• يظل RLS هو خط دفاعك الأخير في الجداول الحساسة: يقوم المدقق بتحديد شكل SQL، وليس حقوق العمل على البيانات.

المحرك قابل للقراءة بدقة: يتم قبول طلبات SELECT فقط. يتم رفض أي محاولة لإنشاءINSERTأو UPDATEأو DELETEأو DROPأو CREATE أو ALTER بواسطة القالب قبل التنفيذ - هذه ليست اصطلاحًا سريعًا، إنها قاعدة مفروضة على مستوى شجرة بناء الجملة.

الحدود الهيكلية الأخرى: لا توجد استعلامات فرعية، ولا CTE/WITH، ولا UNION، وقائمة بيضاء مغلقة مكونة من عشر وظائف SQL. السؤال الذي يستدعي بشكل طبيعي استعلامًا فرعيًا ("العملاء الذين لم يطلبوا مطلقًا") يجب إعادة صياغته ليتناسب مع SELECTالبسيط، أو التعامل معه بشكل مختلف من جانب التطبيق.

يغطي NL2SQL الأسئلة المنظمة حول بياناتك العلائقية. بالنسبة للأسئلة حول المحتوى غير المنظم (المستندات والملاحظات والتذاكر)، يعتمد RAG الأصلي لـ Aurabase على pgvector وبحث HNSW. تم تفصيل كلتا الإمكانيتين – وكيفية دمجهما في وكيل – في Native AI على صفحة Postgres.