Agente IA sobre dados estruturados: text-to-SQL com Gemini + BigQuery na prática
RAG cuida de documento. Mas e quando a pergunta é sobre dado estruturado em BigQuery, Snowflake ou PostgreSQL? Padrão text-to-SQL com Gemini que funciona — e o que ainda exige humano.
Fabiano Brito
CEO & Founder
| Aspecto | RAG Tradicional | Text-to-SQL (Gemini) |
|---|---|---|
| Tipo de Dado | Não estruturado (PDFs, Manuais, Docs) | Estruturado (Tabelas, BigQuery, SQL) |
| Tipo de Resposta | Resumos textuais e síntese de documentos | Números exatos, tabelas e gráficos |
| Precisão Analítica | Aproximada (sujeita a alucinações textuais) | Exata e determinística (validada por parser) |
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)
Input bruto do usuário, com contexto da sessão.
Agente busca em catálogo as tabelas que cobrem o tema (semantic layer).
Gemini 2.5 Pro produces query parametrizada no dialeto do warehouse.
Parser SQL + whitelist de operações + ACL + dry-run.
BigQuery/Snowflake/Postgres com identidade do usuário, não service account.
Agente formata resultado + sugere visualização.
Número + tabela + gráfico opcional + a query usada (para auditoria).
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.
Mapeamento de Sinônimos
Garante que termos de negócio variados apontem de forma consistente para a mesma coluna física no banco de dados.
Métricas Pré-calculadas
Centraliza fórmulas complexas de agregação, evitando que o modelo tente deduzir ou recriar lógicas de cálculo dinamicamente.
Filtros Implícitos
Aplica automaticamente regras de negócio cruciais, como desconsiderar registros de teste ou transações canceladas.
Relações de Schema
Informa explicitamente ao modelo como as tabelas se conectam (JOINs), eliminando adivinhações de chaves estrangeiras.
Ferramentas: dbt + Looker semantic layer, Cube.js, ou definição YAML própria. Em projetos Autenticare, padronizamos em YAML versionado.
💡 Dica de Produção
Sempre execute a validação de dry-run no BigQuery antes de rodar a query final. Isso valida a sintaxe e estima o custo de processamento sem gastar recursos desnecessários.
Padrões de prompt para text-to-SQL
Inclua semp
Perguntas Frequentes
Qual é a principal vantagem de usar text-to-SQL com Gemini e BigQuery?
Com text-to-SQL bem feito, o agente retorna o número correto com um gráfico, ao invés de apenas indicar para consultar o BI.
Quais são os passos da arquitetura padrão para text-to-SQL com Gemini e BigQuery?
A arquitetura padrão envolve 7 passos, desde a pergunta em linguagem natural até a resposta auditável, incluindo recuperação de schema, geração de SQL, validação, execução e pós-processamento.
Por que o 'semantic layer' é um componente chave na arquitetura text-to-SQL?
Sem um 'semantic layer', o modelo pode adivinhar nomes de tabelas e colunas, comprometendo a precisão dos resultados.
O que é um 'semantic layer' no contexto de text-to-SQL?
O 'semantic layer' é um catálogo curado que contém tabelas e colunas com descrições, sinônimos, relações entre tabelas, métricas pré-definidas, filtros padrão e granularidade temporal e geográfica.
Leia também
Quer implementar Text-to-SQL na sua empresa?
Fale com nossos especialistas em dados e IA para desenhar uma arquitetura segura, governada e integrada ao seu BigQuery. Conte com a nossa Fábrica de Agentes para acelerar a implementação.
Falar com um especialista →