チュートリアル: Postgres 上で NL2SQL エンドポイントを構築する

この英語のテキストはフランス語のオリジナルから自動的に生成されたもので、まだレビューされていません。

このページは自動翻訳されました。英語版が正式です。

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.

目的

何を構築するか

自然言語の質問を受信したエンドポイントは、それを検証済みの制限付き SQL クエリに変換し、結果を返します。エンジンは生成された SQL を制御なしで実行することはありません。各クエリはデータベースに到達する前に構文検証を経ます。

情報

このチュートリアルでは、@aurabase/aurabase-js JavaScript SDK と同等の生の HTTP 呼び出しを使用するため、どの言語からでも進めることができます。

ボンネットの下で

NL2SQL エンジンの仕組み

質問は、構成された LLM (OpenAI、Anthropic (Claude)、または Gemini、3 つのネイティブプロバイダー) を通過し、候補 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)→有界LIMIT→SELECT実行

クエリされたダイアグラムは、リクエストによって提供されることはありません。プロジェクトの実際のベースからイントロスペクトされます。リクエスト本文で送信された schema、 allowed_schema または schema_context フィールドは、暗黙的に無視されるのではなく、明示的に拒否されます (400 エラー)。実際に何が存在するかはサーバーのみが決定します。

ステップ1

NL2SQL エンドポイントを構成する

JavaScript SDK を使用すると、Aurabase クライアントは aura.ai.nl2sql()を公開します。署名は nl2sql(question, options)です。スキーマは署名の一部ではなく、サーバー側でイントロスペクトされます。

app/api/ask/route.tstypescript

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

raw HTTP では、エンドポイントは POST /v1/ai/{project_id}/nl2sqlで、プロジェクト API キーによって認証されます。

terminalbash

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

サーバーによって拒否されたフィールド

リクエストの本文で schema、 allowed_schema、 schema_context を送信しないでください。クエリされるスキーマはサーバーによって決定され、これらのフィールドは暗黙的に上書きされるのではなく、明示的に拒否されます (400)。

ステップ2

フランス語で実際の質問をテストしてください

送信された質問: 「プレミアム顧客による今月の注文は何件ありましたか?」実際にレンダリングされる SQL の形式は次のとおりです (テーブル名と列はスキーマによって異なります)。

回答（抜粋）json

{
  "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 がスキーマにないテーブルをクエリする場合、メッセージでは実際に使用可能なテーブルの名前が表示されます。

ステップ3

安全な生産

デプロイ前の 3 つのチェック: 行の上限 (LIMIT) がボリュームに適合しているか、エンジンによって使用される Postgres ロールがプロジェクトスキーマに制限されたままであるか、機密テーブルにアクティブな RLS ポリシーがあるか — NL2SQL はアプリケーションの残りの部分と同じデータベースにクエリを実行しますが、デフォルトでは拡張アクセス権がありません。

デフォルトの行キャップはサーバー側で構成できます。サーバーの上限を超える要求された値は、暗黙的に削減されるのではなく、明示的に拒否されます。
システムカタログ (pg_catalog、 information_schema) および非プロジェクトスキーマへのアクセスは、RLS ポリシーに関係なく、バリデーターによってブロックされます。
RLS は機密テーブルに対する最後の防御線であり、バリデーターはデータに対するビジネス上の権利ではなく、SQL の形式を制限します。

正直さ

注意すべき電流制限

エンジンは厳密に読み取り可能です。SELECT リクエストのみが受け入れられます。テンプレートによって生成されたINSERT、 UPDATE、 DELETE、 DROP、 CREATE または ALTER への試みは実行前に拒否されます。これはプロンプト規則ではなく、構文ツリーレベルで課せられるルールです。

その他の構造上の制限: サブクエリなし、CTE/WITH なし、UNION なし、および 10 個の SQL 関数のクローズドホワイトリスト。必然的にサブクエリを必要とする質問 (「注文したことのない顧客」) は、単純な SELECTに収まるように再定式化するか、アプリケーション側で別の方法で処理する必要があります。

さらに進んでください

RAG とエージェント

NL2SQL は、リレーショナルデータに関する構造化された質問をカバーします。非構造化コンテンツ (ドキュメント、メモ、チケット) に関する質問については、Aurabase のネイティブ RAG は pgvector と HNSW 検索に依存します。両方の機能、およびそれらをエージェントで組み合わせる方法については、Postgres のネイティブ AI ページで詳しく説明されています。

よくある質問

よくある質問

NL2SQL は複雑なスキーマ (複数の結合) で動作しますか?+

複数テーブルの結合はバリデーターによってサポートされています。一方、サブクエリと CTE/WITH は明示的に拒否されます。自然にサブクエリを必要とする質問は、結合を伴う単純な SELECT に適合するように再定式化するか、アプリケーション側で処理する必要があります。

NL2SQL にはどの LLM プロバイダーを選択すればよいですか?+

3 つのネイティブプロバイダー (OpenAI、Anthropic/Claude、Gemini) は、バリデーターによって同等に扱われます。生成された SQL の検証において構造的な利点を持つものはありません。コストとレイテンシーは、プロジェクト用に構成された特定のモデルによって異なります。一般的な推奨事項に従うのではなく、独自のボリュームで比較してください。