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 エラー)。実際に何が存在するかはサーバーのみが決定します。
NL2SQL エンドポイントを構成する
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)
}
raw 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
}'
リクエストの本文で schema、 allowed_schema、 schema_context を送信しないでください。クエリされるスキーマはサーバーによって決定され、これらのフィールドは暗黙的に上書きされるのではなく、明示的に拒否されます (400)。
フランス語で実際の質問をテストしてください
送信された質問: 「プレミアム顧客による今月の注文は何件ありましたか?」実際にレンダリングされる 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 がスキーマにないテーブルをクエリする場合、メッセージは実際に使用可能なテーブルの名前を示します。
安全な生産
デプロイ前の 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 で詳しく説明されています。