Учебное пособие: создание конечной точки NL2SQL на Postgres

Конечная точка, которая получает вопрос на естественном языке, преобразует его в проверенный и ограниченный запрос SQL, а затем возвращает результат. Движок никогда не выполняет сгенерированный SQL без контроля: каждый запрос проходит синтаксическую проверку, прежде чем попасть в базу данных.

Вопрос проходит через настроенный LLM — OpenAI, Anthropic (Claude) или Gemini, три собственных поставщика, — который генерирует кандидатный SQL. Этот SQL никогда не выполняется как есть: он проходит через валидатор, который анализирует его синтаксическое дерево (sqlparser), разрешает только простые запросы SELECT и добавляет ограниченный LIMIT, если он отсутствует.

Валидатор явно отклоняет CTE/WITH, подзапросы, UNION, предложения блокировки (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, аутентифицированная ключом API проекта.

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.