💬 O que é Text-to-SQL
Text-to-SQL é a capacidade de transformar uma pergunta em linguagem natural em uma query SQL válida e executável. O usuário fala como humano. O agente traduz para SQL. O banco executa. O resultado volta em linguagem natural. É a interface mais democrática entre executivos e dados estruturados.
Como funciona na prática
FROM contracts
WHERE contract_start >= '2025-10-01'
GROUP BY client_name
ORDER BY receita DESC
LIMIT 5;
⚠️ Onde falha sem dados limpos
Text-to-SQL sobre dados sujos = respostas confiantes sobre mentiras. Se o campo mrr_brl tem valores negativos por bug de importação, o agente vai somá-los como se fossem legítimos e responder com absoluta convicção. O agente não vai saber que o dado está errado. Vai responder com convicção.
🏗️ Arquitetura Completa
A arquitetura Text-to-SQL com DuckDB é surpreendentemente simples. Cada camada tem uma responsabilidade única e pode ser inspecionada, testada e substituída independentemente.
Pergunta em linguagem natural
O usuário (ou outro agente) faz uma pergunta de negócio em texto livre. Sem SQL, sem formato específico.
Claude Code gera o SQL
Com o schema e o data dictionary no contexto, o agente traduz a pergunta para SQL válido. O SQL pode ser inspecionado antes de executar — isso é fundamental para auditoria.
DuckDB executa localmente
DuckDB lê os CSVs ou Parquets diretamente do disco, executa a query em memória, retorna apenas o resultado filtrado. Sem servidor, sem setup complexo, sem dados na nuvem.
Resultado compacto no contexto
5, 10, 20 linhas. O contexto recebe apenas o que importa para responder a pergunta. O agente formula a resposta em linguagem natural com os dados reais.
Por que DuckDB e não Pandas?
DuckDB executa SQL diretamente em arquivos CSV e Parquet, sem carregar tudo na memória. Para datasets de 1GB+, Pandas trava. DuckDB processa em segundos. Para datasets menores, DuckDB também vence — é mais simples, mais rápido, e o SQL gerado pelo agente é auditável por qualquer pessoa.
🚫 Por que Você Não Joga Milhões de Linhas no Contexto
A intuição errada: "se eu jogar todos os dados no contexto, o agente vai ter tudo que precisa para responder". A realidade: contexto tem limite, custo, e qualidade de raciocínio que degrada com volume. SQL é o filtro inteligente.
✗ Abordagem ingênua — dados no contexto
- • 18.000 linhas de CSV no contexto
- • ~1.5M tokens usados só nos dados
- • Custo: ~$15-30 por query
- • Qualidade de resposta: degradada
- • Impossível para datasets > 100k linhas
- • Latência: 30-60 segundos
✓ Text-to-SQL com DuckDB
- • Schema + data dictionary no contexto (~500 tokens)
- • SQL gerado (~200 tokens)
- • Resultado: 5-20 linhas no contexto
- • Custo: ~$0.01 por query
- • Escala para bilhões de linhas
- • Latência: 2-5 segundos
A regra de ouro do contexto
Você não joga 18.000 linhas no contexto. Você pede ao agente para escrever o SQL, e o DuckDB retorna as 5 linhas que importam. O contexto recebe o resultado compacto — não o dataset bruto. Esse é o princípio de eficiência de contexto mais importante da arquitetura.
✅ O Prompt de Auditoria como Pré-Requisito Absoluto
Text-to-SQL não funciona sobre dados sujos. É uma verdade inconveniente que muitos ignoram. Antes de liberar qualquer pergunta de negócio via SQL, os dados precisam passar pelo gate de qualidade completo.
O pipeline correto — auditoria antes de Text-to-SQL
⚠️ O perigo do GIGO em Text-to-SQL
GIGO — Garbage In, Garbage Out. Um campo de receita com valores negativos por bug de importação vai ser somado como se fossem estornos legítimos. O CEO vai receber um número errado com a aparência de análise sofisticada. A confiança no sistema vai aumentar — enquanto as decisões são tomadas sobre dados incorretos.
💡 Exemplos Reais de Text-to-SQL
A melhor forma de entender Text-to-SQL é vê-lo em ação. Os exemplos abaixo são reais — tipo de pergunta, SQL gerado e resultado obtido. Cada um representa um padrão que você vai usar repetidamente em projetos reais.
Exemplo 1 — Top clientes por receita
Prompt ao agente:
SQL gerado:
SUM(e.revenue_brl) AS total_revenue
FROM engagements e
JOIN clients c ON e.client_id = c.id
WHERE e.is_active = 1
GROUP BY c.client_name
ORDER BY total_revenue DESC
LIMIT 5;
Resultado: 5 linhas em 1.2 segundos. Sem jogar nada no contexto.
Exemplo 2 — Churn dos últimos 90 dias
Pergunta:
SQL gerado:
cancellation_date,
mrr_brl AS mrr_perdido
FROM contracts
WHERE is_active = 0
AND cancellation_date >= CURRENT_DATE - 90
ORDER BY cancellation_date DESC;
Exemplo 3 — Utilização por consultor
Pergunta:
SQL gerado:
ROUND(AVG(utilization_pct), 1) AS avg_utilization
FROM timesheets
WHERE week_start = DATE_TRUNC('week', CURRENT_DATE)
GROUP BY consultant_name
ORDER BY avg_utilization DESC;
💡 O SQL é auditável — e isso é uma vantagem
Diferente de uma análise em prosa, o SQL gerado pode ser revisado por qualquer pessoa que saiba a linguagem. O CEO pode mostrar para o CFO: "aqui está exatamente como esse número foi calculado". Isso é transparência que planilhas Excel não conseguem oferecer.
⚠️ Limites do Text-to-SQL
Text-to-SQL é poderoso dentro do seu domínio — dados estruturados, perguntas analíticas, resultados tabulares. Fora desse domínio, ele falha de formas previsíveis. Conhecer os limites é saber quando usar outra abordagem.
✗ Quando Text-to-SQL não funciona
- ✗Dados não-estruturados (texto, PDFs, emails)
- ✗Queries com 10+ joins aninhados (SQL gerado fica inválido)
- ✗Perguntas que requerem raciocínio além dos dados (previsões, causalidade)
- ✗Dados sem schema claro (JSON deeply nested)
- ✗Real-time com requisitos de latência < 100ms
✓ Alternativas por caso
- →Texto: RAG com vector database
- →Joins complexos: views pré-computadas no DuckDB
- →Previsões: Python com scikit-learn ou Prophet
- →JSON aninhado: normalização prévia ou jq
- →Real-time: streaming pipeline (Kafka + Flink)
O sinal de que Text-to-SQL não está servindo
Se o SQL gerado falha mais de 20% das vezes, ou se o agente precisa de mais de 3 tentativas para gerar uma query correta, é sinal de que ou os dados precisam ser normalizados antes, ou a pergunta está fora do domínio do SQL. Não tente forçar.
✅ Resumo do Módulo
Próximo Módulo:
3.5 — ⚖️ Primitivos Corretos — Skill vs Regra vs Hook vs Script: o erro mais silencioso da stack