튜토리얼: Postgres에서 NL2SQL 엔드포인트 구축

자연어 질문을 수신하고 이를 검증되고 제한된 SQL 쿼리로 변환한 다음 결과를 반환하는 엔드포인트입니다. 엔진은 제어 없이 생성된 SQL을 실행하지 않습니다. 각 쿼리는 데이터베이스에 도달하기 전에 구문 검증을 거칩니다.

질문은 후보 SQL을 생성하는 세 가지 기본 공급자인 OpenAI, Anthropic(Claude) 또는 Gemini와 같은 구성된 LLM을 통해 진행됩니다. 이 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에서 엔드포인트는 프로젝트 API 키로 인증된 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 없음, 10개 SQL 함수의 폐쇄형 화이트리스트. 자연스럽게 하위 쿼리("주문한 적이 없는 고객")를 요구하는 질문은 간단한 SELECT에 맞게 다시 공식화되거나 애플리케이션 측에서 다르게 처리되어야 합니다.

NL2SQL은 관계형 데이터에 대한 구조화된 질문을 다룹니다. 구조화되지 않은 콘텐츠(문서, 메모, 티켓)에 대한 질문의 경우 Aurabase의 기본 RAG는 pgVector 및 HNSW 검색을 사용합니다. 두 가지 기능과 이를 에이전트에 결합하는 방법은 Postgres의 네이티브 AI 페이지에 자세히 설명되어 있습니다.