Aurabase的 NL2SQL 引擎是原生 AI 的一部分,集成到 后端中:不是放在一起的第三方服务。遵循本指南的先决条件:现有的 Aurabase 项目、示例的简单数据库架构以及项目 API 密钥。
你将构建什么
接收自然语言问题、将其转换为经过验证且有界的 SQL 查询,然后返回结果的端点。引擎绝不会在没有控制的情况下执行生成的 SQL:每个查询在到达数据库之前都会经过语法验证。
本教程使用 @aurabase/aurabase-js JavaScript SDK 和等效的原始 HTTP 调用,因此您可以使用任何语言进行操作。
NL2SQL 引擎如何工作
该问题通过已配置的 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)→有界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)
}
在原始 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 查询不在您的模式中的表,则消息会命名实际可用的表。
安全生产
部署前进行三项检查:行上限 (LIMIT) 是否适合您的卷,引擎使用的 Postgres 角色是否仍限制于项目架构,以及敏感表是否具有活动的 RLS 策略 — NL2SQL 与应用程序的其余部分查询相同的数据库,默认情况下它没有扩展访问权限。
- 默认线路上限可在服务器端配置;高于服务器上限的请求值会被明确拒绝,而不是默默减少。
- 无论您的 RLS 策略如何,验证器都会阻止对系统目录(
pg_catalog、information_schema)和非项目架构的访问。 - RLS 仍然是敏感表的最后一道防线:验证器限制 SQL 的形式,而不是数据的业务权限。
需要注意的当前限制
引擎是严格可读的:仅接受 SELECT 请求。模板生成的INSERT、 UPDATE、 DELETE、 DROP、 CREATE 或 ALTER 的任何尝试在执行前都会被拒绝 - 这不是提示约定,而是在语法树级别强加的规则。
其他结构限制:没有子查询、没有 CTE/WITH、没有 UNION 以及十个 SQL 函数的封闭白名单。自然需要子查询(“从未订购过的客户”)的问题必须重新表述以适合简单的 SELECT,或者在应用程序端进行不同的处理。
RAG 和代理
NL2SQL covers structured questions about your relational data. For questions about unstructured content (documents, notes, tickets), Aurabase's native RAG relies on pgvector and an HNSW search. Both capabilities — and how to combine them in an agent — are detailed on the Native AI on Postgres page.