API/AI Gateway/Natural Language to SQL

Natural Language to SQL

POST/v1/ai/{project_id}/nl2sql

Converts natural language into secure, read-only PostgreSQL queries checked by an Abstract Syntax Tree (AST) parser.

nl2sql.tstypescript

const { data, error } = await aura.ai.nl2sql(
  'What are the 10 most recent user registrations?',
  { dialect: 'postgresql', limit: 10 }
)
console.log('Safe SQL Query:', data?.sql)
console.log('Injected Limit:', data?.limit, 'Confidence:', data?.confidence)

200.jsonjson

{
  "data": {
    "sql": "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 10;",
    "explanation": "Retrieves the latest 10 users ordered by creation timestamp.",
    "confidence": 0.96,
    "limit_injected": false,
    "limit": 10
  }
}

Request

Parameters

Parameter	Type	Required	Description
`question`	`string`	yes	Natural language question about the project's data.
`dialect`	`string`	no	Database dialect. Accepts `'postgresql'` or `'postgres'`.
`examples`	`object[]`	no	Optional few-shot examples `[{ question, sql }]` guiding query generation.
`limit`	`number`	no	Maximum row limit injected if omitted by model (default `100`, max `1000`).

Security

AST Mutation Guards

Info

The server parses the generated SQL with an Abstract Syntax Tree (AST) engine prior to returning it:

Any non-SELECT mutation statement (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE) is rejected immediately with HTTP 400.
System catalog tables (pg_catalog, information_schema) are strictly disallowed.
If the model omits a LIMIT clause, the server injects LIMIT 100 (capped at 1000) and marks limit_injected: true.

v1.0 · revised Oct 31, 2026
↗ OpenAPI spec↗ GitHub

← PREVIOUS

RAG query & ingest