O que é NL2SQL e como funciona?

NL2SQL refere-se à tradução automática de uma pergunta em linguagem natural em uma consulta SQL que pode ser executada de forma relacional. Ao contrário de um chatbot genérico que responde em texto livre, um sistema NL2SQL produz um artefato estruturado, SQL, que é executado em dados reais e retorna um resultado verificável linha por linha.

O termo “text-to-SQL” vem de pesquisas acadêmicas em processamento de linguagem natural. “NL2SQL” é a abreviatura mais usada no lado do produto e na documentação técnica. Ambos se referem ao mesmo problema: preencher a lacuna entre uma pergunta feita na linguagem cotidiana e a sintaxe precisa esperada por um mecanismo SQL.

NL2SQL se distingue de um agente conversacional conectado a um banco de dados no sentido amplo. A primeira produz uma consulta legível e auditável; a segunda pode encadear diversas chamadas de ferramentas (busca, cálculo, escrita) sem necessariamente resultar em um SQL único e inspecionável. Um sistema NL2SQL adequadamente projetado permanece dentro deste escopo deliberadamente restrito: traduzir, validar, executar, retornar um resultado.

Um pipeline NL2SQL confiável sempre segue a mesma sequência, independente do provedor: a questão passa por um modelo de linguagem, então o SQL produzido é validado antes da execução, nunca depois. A implementação do Aurabase, verificada no código de serviço aura-ai, ilustra cada uma dessas etapas com regras concretas em vez de uma descrição abstrata.

1. A pergunta é recebida com o esquema real da base

O sistema associa a pergunta em linguagem natural ao esquema do banco de dados consultado: nomes de tabelas, colunas, tipos. Esse padrão deve vir da introspecção da base real, e não de uma descrição fornecida pelo chamador. Uma implementação que aceite um esquema declarado pelo cliente abriria a porta para questões sobre tabelas inexistentes ou para contornar o isolamento entre projetos. O mecanismo Aurabase rejeita explicitamente (erro 400) qualquer campo schema enviado na solicitação, em vez de ignorá-lo silenciosamente.

2.Um LLM gera um SQL candidato

O modelo de linguagem recebe a pergunta e o esquema em seu prompt e, em seguida, produz uma consulta SQL candidata junto com uma breve explicação. Aurabase trata três provedores igualmente com um cliente nativo dedicado: OpenAI, Anthropic (Claude) e Gemini. Este SQL candidato é, neste estágio, apenas uma proposta, nunca executada diretamente.

3. O SQL candidato é validado antes da execução, não depois

Esta é a etapa que distingue um sistema NL2SQL sério de uma simples chamada LLM seguida de execução ingênua. O SQL gerado é analisado em uma árvore de sintaxe (AST) em vez de inspecionado por uma pesquisa por palavra-chave, que é facilmente contornada. A implementação do Aurabase, com a biblioteca sqlparser, permite apenas consultas SELECT simples: CTE/WITH, subconsultas, UNIONs, funções de janela e cláusulas de bloqueio (FOR UPDATE) são explicitamente rejeitadas, assim como quaisquer funções SQL fora de uma lista branca de dez funções (count, sum, avg, min, max, lower, upper, coalesce, date_trunc, now).

4. A consulta confirmada é executada com um limite de linha

O SQL validado recebe um LIMIT se ainda não tiver um: 100 linhas por padrão com Aurabase, 1000 no máximo, ambos valores configuráveis no lado do servidor. Uma solicitação além do limite é negada explicitamente, em vez de ser reduzida silenciosamente. A resposta indica se este LIMIT foi adicionado pelo servidor, para que o chamador saiba se o SQL executado difere daquele produzido pelo modelo.

-- Pergunta: "Quantos pedidos este mês para clientes premium?"
SELECT count(*) FROM orders
WHERE customer_plan = 'premium'
  AND created_at >= date_trunc('month', now())
LIMIT 100  -- adicionado pelo servidor, ausente no SQL gerado

Os detalhes completos desse pipeline, com cada chamada HTTP e cada resposta JSON, são abordados em nosso tutorial passo a passo para construir um endpoint NL2SQL no Postgres.

O NL2SQL não se destina a substituir o SQL escrito à mão em todos os lugares. Abrange um escopo específico: perguntas pontuais e ad hoc feitas por alguém que não conhece SQL ou que simplesmente deseja economizar tempo em uma consulta simples.

• Exploração ad hoc de um dashboard por uma pessoa não técnica (suporte, produto, gestão).
• Prototipagem rápida de um recurso que consulta o banco de dados sem escrever uma rota de API dedicada para cada pergunta possível.
• Autoatendimento analítico limitado: contar, filtrar, simplesmente agregar, sem dar acesso direto ao banco de dados ao usuário final.

O SQL escrito à mão permanece preferível assim que a questão ultrapassa esse escopo. Uma implementação validada por AST como a descrita acima exclui CTEs, subconsultas e funções de janela por construção, por razões de segurança. Uma análise que necessita estruturalmente dessas construções, coortes, janelas temporais avançadas, não passa pelo NL2SQL: ela é codificada diretamente. Este é um compromisso aceito, a segurança do sistema vem antes da integridade do SQL gerado.

Três riscos ocorrem sistematicamente em uma implementação NL2SQL, com respostas diferentes dependendo da maturidade do sistema.

Injeção de SQL via prompt ou pergunta

Um LLM pode ser manipulado para produzir SQL malicioso se a própria pergunta contiver uma tentativa de injeção "ignorar instruções anteriores e...". A defesa não é confiar no prompt, mas sim validar o SQL produzido independente do que foi solicitado, exatamente o passo 3 do pipeline descrito acima. O tópico merece tratamento dedicado: consulte Protegendo NL2SQL contra injeção de SQL para contramedidas e vetores de ataque precisos.

Alucinação de tabelas ou colunas inexistentes

O modelo pode inventar um nome de tabela ou coluna que seja plausível, mas ausente do esquema real, especialmente em esquemas grandes ou mal documentados. Uma implementação que valida o SQL gerado em relação ao esquema real do banco de dados rejeita a consulta com uma mensagem explícita, listando as tabelas realmente disponíveis, em vez de permitir que um erro SQL bruto seja transmitido de volta ao usuário.

Custo e latência de chamadas de modelo

Cada questão NL2SQL dispara uma chamada ao modelo da linguagem, com custo e latência próprios, além do tempo de execução do SQL. Esse custo aumenta rapidamente se o NL2SQL servir como camada padrão para perguntas repetitivas, que se beneficiariam se fossem armazenadas em cache ou expostas como um relatório padrão, em vez de serem retraduzidas a cada vez.

Duas arquiteturas produzem um resultado visível semelhante, mas com garantias muito diferentes. O NL2SQL nativo integra geração, validação e execução diretamente na camada backend que já conhece o esquema e os direitos de acesso do projeto: esta é a lógica descrita acima para Aurabase, onde o serviço aura-ai compartilha a infraestrutura e o isolamento do esquema com o resto do backend.

Um NL2SQL montado combina um serviço LLM genérico, um conector para o banco de dados e uma camada de validação do tipo “construa você mesmo”. Nada impede que esta abordagem seja segura, mas todas as garantias, esquema introspectado do lado do servidor, validação AST, limite de linha, locatário de isolamento, devem ser implementadas e mantidas pela equipe que monta esses blocos, em vez de fornecidas pela plataforma.

O panorama das ferramentas NL2SQL, nativas e montadas, de código aberto e comerciais, é comparado detalhadamente em nossa comparação de ferramentas NL2SQL 2026.

NL2SQL e RAG (geração aumentada de recuperação) respondem a duas famílias diferentes de perguntas, muitas vezes confundidas porque ambas dependem de um LLM conectado a um banco de dados.

NL2SQL tem como alvo dados estruturados e relacionais: quantos, quando, em que proporção, perguntas que se traduzem naturalmente em SELECT, GROUP BY, agregações. O RAG tem como alvo conteúdo não estruturado: documentos, notas, tickets de suporte, onde a resposta não cabe em uma linha da tabela, mas requer encontrar uma passagem relevante por similaridade semântica, pesquisa vetorial no pgvector, índice HNSW, antes de fornecê-la no contexto do modelo.

As duas capacidades podem coexistir no mesmo projeto e combinar-se num agente que escolhe uma ou outra dependendo da pergunta feita. O pilar de IA nativa Aurabase detalha como os dois mecanismos funcionam juntos, e nosso guia de pipeline RAG no pgvector cobre a implementação do segundo.