Agente IA sobre dados estruturados: text-to-SQL com Gemini + BigQuery na prática

Metade das perguntas que executivos fazem ao "ChatGPT da empresa" são analíticas: comparações, totais, tendências, segmentação. Sem text-to-SQL, agente devolve "consulte o BI". Com text-to-SQL bem feito, agente devolve número certo com gráfico.

Arquitetura padrão (7 passos)

O componente chave: semantic layer

Modelo não decora schema do seu data warehouse. Sem semantic layer, ele chuta nomes de tabela e coluna.

Semantic layer é catálogo curado:

• Tabelas e colunas com descrição em PT/EN.
• Sinônimos ("receita" = "revenue" = "faturamento").
• Relações entre tabelas (chaves estrangeiras explícitas).
• Métricas pré-definidas ("ticket médio = SUM(valor)/COUNT(pedido)").
• Filtros padrão ("apenas pedidos confirmados").
• Granularidade temporal e geográfica.

Ferramentas: dbt + Looker semantic layer, Cube.js, ou definição YAML própria. Em projetos Autenticare, padronizamos em YAML versionado.

Padrões de prompt para text-to-SQL

Inclua sempre no prompt:

• Schema das tabelas relevantes (DDL completo).
• 3-5 exemplos de pergunta → SQL bem formada.
• Dialeto explícito ("PostgreSQL 15", "BigQuery Standard SQL").
• Restrições: "use sempre LIMIT 1000", "nunca DELETE/UPDATE/DROP", "use parâmetros nomeados".
• Formato de saída: SQL puro entre code fence, sem comentário extra.
• Regra de incerteza: "se não houver dado para responder, devolva null + explicação".

Veja padrões mais amplos em prompt engineering corporativo.

Validação obrigatória antes de executar

1. Parser SQL: garante que é SQL válido (não comentário, não texto solto).
2. Whitelist de operações: apenas SELECT.
3. Whitelist de tabelas: agente pode tocar apenas tabelas marcadas como "agent-accessible".
4. Verificação de ACL: usuário tem permissão na tabela?
5. Dry run em BigQuery (custo zero, valida sintaxe e estima bytes).
6. Limite de bytes processados (cap de custo).
7. Timeout de execução.

Padrão "agente analítico" híbrido

Em casos reais, melhor combinar:

• Métricas pré-definidas (semantic layer): para perguntas comuns, executa query pronta com parâmetros. Mais rápido e mais confiável.
• Text-to-SQL livre: para perguntas ad-hoc fora do catálogo. Validação extra.
• RAG sobre dicionário: agente consulta documentação de negócio (políticas, definições) antes de gerar SQL.

O que dá errado em text-to-SQL ingênuo

Joins esquecidos

"Quanto vendemos por região?" — agente esquece JOIN com tabela de loja, devolve número errado. Solução: joins recomendados no semantic layer.

Filtros não declarados

"Faturamento mensal" — agente não filtra status="confirmado". Sempre incluir filtro padrão no semantic layer.

Granularidade temporal

"Vendas de março" — março de qual ano? Sem contexto, agente assume errado. Inclua data atual no prompt + regra: "se ano não especificado, usar ano vigente".

Conversão de moeda

Multinacional com BRL, USD, ARS na mesma tabela: agente soma tudo sem converter. Métrica derivada no semantic layer resolve.

Confusão entre métricas similares

"Receita líquida" vs "receita bruta" vs "GMV" — sem definição clara, agente escolhe mal. Glossário com definição canônica resolve.

Avaliação específica

Gold set para text-to-SQL difere de RAG. Estrutura:

• Pergunta em linguagem natural.
• SQL esperado (canônico) ou conjunto de SQLs equivalentes.
• Resultado esperado (números).
• Métrica primária: execution match (resultado bate, mesmo se SQL escrito diferente).
• Métrica secundária: logical form match (estrutura SQL correta).

Recall de 90%+ em execution match é alvo realista para corpus de 100-300 perguntas. Detalhes em avaliação de agentes em produção.

Custos a controlar

• Bytes BigQuery: limite por query e por usuário/dia.
• Tokens Gemini: schema grande no prompt come tokens. Selecionar apenas tabelas relevantes via primeira chamada (router).
• Cache de query: pergunta idêntica em janela curta = resultado em cache, sem reexecutar.

Governança

• Audit log: pergunta + SQL gerado + bytes processados + resultado + usuário.
• Identidade real: query roda com permissão do usuário, não service account.
• PII handling: nunca expor CPF/e-mail em resposta agregada — agregação é mandatória em colunas sensíveis.
• RIPD para análise sobre dados pessoais — veja RIPD para projetos Gemini Enterprise.

Quando NÃO usar text-to-SQL

• Perguntas que exigem julgamento ("o que devemos fazer?"): combine com análise complementar.
• Decisões críticas (preço, oferta a cliente): agente sugere, humano decide.
• Análise complexa multi-tabela com lógica de negócio profunda: melhor BI tradicional + agente para resumir.

Text-to-SQL funciona quando o agente sabe o que não pode tocar. Semantic layer curado + whitelist + dry-run >> prompt gigante com 200 tabelas jogadas dentro.