API/AI Gateway/Linguagem Natural para SQL

Linguagem Natural para SQL

POST/v1/ai/{project_id}/nl2sql

Converte linguagem natural em consultas PostgreSQL seguras e somente leitura, verificadas por um analisador Abstract Syntax Tree (AST).

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

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

Solicitação

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`question`	`string`	sim	Pergunta de linguagem natural sobre os dados do projeto.
`dialect`	`string`	não	Dialeto de banco de dados. Aceita `'postgresql'` ou `'postgres'`.
`examples`	`object[]`	não	Exemplos opcionais de poucas tentativas `[{ question, sql }]` orientando a geração de consultas.
`limit`	`number`	não	Limite máximo de linhas injetado se omitido pelo modelo (padrão `100`, max `1000`).

Segurança

AST Protetores de Mutação

Informações

O servidor analisa o SQL gerado com um mecanismo Abstract Syntax Tree (AST) antes de retorná-lo:

Qualquer instrução de mutação não SELECT (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE) é rejeitada imediatamente com HTTP 400.
Tabelas de catálogo do sistema (pg_catalog, information_schema) são estritamente proibidas.
Se o modelo omitir uma cláusula LIMIT, o servidor injeta LIMIT 100 (limitado a 1000) e marca limit_injected: true.

v1.0 · revisado 31 de out. de 2026
↗ Especificação OpenAPI↗ GitHub

← ANTERIOR

RAG query & ingest