O que um agente de analytics precisa saber da sua empresa antes de responder

Resumo executivo

A pergunta é simples: qual foi a receita de agosto? O agente de analytics gera o SQL, a consulta executa sem erro e o número sai. Só não é o número da controladoria. Um agente de analytics, o sistema que recebe uma pergunta em linguagem natural, consulta o data warehouse, o banco analítico da empresa, e devolve o resultado, erra assim porque o esquema do banco não informa o que a empresa chama de receita, qual junção duplica linhas, em que dia o mês fecha e quem pode ver o quê.

Este artigo inventaria seis camadas de contexto que o agente precisa receber antes da primeira pergunta: definições de métrica, esquema e junções, tempo e granularidade, regras de negócio, permissões e critérios de recusa. Para cada uma, mostra como a ausência aparece, como representar e como testar. A conclusão é de engenharia: esse contexto se mantém como código, com versão, dono e teste. O esforço compensa quando várias áreas consomem as mesmas métricas; num esquema pequeno com um único time, pode custar mais do que rende.

Por que o mesmo modelo acerta no benchmark e erra no seu warehouse?

Porque o benchmark clássico entrega, junto com a pergunta, quase tudo de que a resposta depende, e o warehouse corporativo guarda essa informação fora do banco. Numa empresa, a regra que decide o número vive num manual de fechamento, numa planilha da controladoria ou na cabeça de duas pessoas.

A literatura mede essa distância, e mede também o quanto ela encolheu. No Spider 2.0, de 2024, com 632 problemas derivados de casos de uso corporativos, o agente dos autores, baseado no modelo o1-preview, resolveu 21,3% das tarefas, contra 91,2% no Spider 1.0 e 73,0% no BIRD. Em outubro de 2026, o placar público da variante Spider 2.0-Snow tem 96,70 no topo e cinco sistemas acima de 90, todos agentes de empresas. Fora dos placares o quadro é outro: no BEAVER, construído a partir de data warehouses privados e de logs reais de consulta, a versão de maio de 2026 reporta 10,8% de acurácia para frameworks agênticos de ponta com o modelo GPT-5.2.

O resultado mais instrutivo vem do EntSQL, de 2026, que acompanha as perguntas de documentos com as regras de negócio. Só com a pergunta e o esquema, o melhor sistema avaliado, o agente de programação Claude Code, acertou 6,8% das consultas em inglês. Com o documento na entrada, 15,9%. Com a evidência relevante já recortada por especialistas, 21,4%. Conhecimento de negócio ajuda quando chega localizado, e ajuda menos do que se esperaria: numa amostra de 212 perguntas, especialistas humanos com a mesma evidência chegaram a 84,0%, contra 20,3% do agente. Receber a regra não garante aplicá-la.

Seis camadas organizam o que falta ao modelo. A tabela resume o sintoma, a representação e o teste de cada uma.

Definições de métrica: o que é receita, cliente ativo e churn aqui

A definição de métrica abre o inventário porque a falha dela não tem aparência de falha. "Receita" pode ser faturada ou reconhecida, bruta ou líquida de impostos e devoluções, contada pela data do pedido ou pela da nota fiscal. "Cliente ativo" depende de uma janela, de 90 dias ou de 12 meses, e "churn", a taxa de perda de clientes, depende de "ativo". Cada combinação produz um SQL correto e um número diferente.

A representação que funciona é declarativa. No formato esquemático abaixo, de uma distribuidora hipotética, a métrica tem nome, sinônimos, expressão, filtros obrigatórios, data de referência, dono e versão. Com isso, o agente deixa de compor a agregação e passa a escolher uma métrica já definida, o que troca um problema de geração aberta por um de seleção. Camada semântica é o nome dessa camada entre o banco e quem consulta: nela, métricas, dimensões e junções são declaradas uma vez, e o SQL é gerado a partir delas.

# Formato esquemático, de uma distribuidora hipotética.
# Não corresponde à sintaxe de nenhuma ferramenta específica.
metrica: receita_liquida
versao: 3            # a v2 incluía frete; alterada em 2026-03
dono: controladoria
sinonimos: [faturamento líquido, vendas líquidas]   # o vocabulário de quem pergunta
descricao: Valor faturado, líquido de impostos sobre venda e de devoluções.
tabela_base: fato_nota_fiscal_item      # grão: uma linha por item de nota
expressao: SUM(valor_item - impostos_venda - valor_devolvido)
data_referencia: data_emissao_nf        # e não data_pedido
filtros_obrigatorios:
  - status_nf = 'AUTORIZADA'
  - tipo_operacao = 'VENDA'             # exclui remessa, bonificação, transferência
  - cliente_intragrupo = FALSE
aditiva_no_tempo: true
dimensoes_permitidas: [regiao, canal, categoria_produto, mes_fiscal]
nao_confundir_com: [receita_bruta, valor_pedido]   # diante de "receita" sem qualificador, o agente pergunta qual

O teste desta camada: perguntas cuja resposta a controladoria já publicou, reexecutadas a cada mudança de definição.

Esquema e junções: tabelas canônicas, chaves e o que não se deve juntar

O esquema físico informa quais colunas existem e cala sobre quais devem ser usadas. Um warehouse com alguns anos de vida acumula cópias, visões legadas e três colunas chamadas dt_ref. Falta ao agente saber qual tabela é a canônica para cada entidade, qual é o grão de cada tabela de fatos (uma linha por pedido, por item ou por parcela) e quais chaves ligam o quê.

A falha característica desta camada é a duplicação por junção. Ao juntar pedidos com itens e somar o valor do pedido, cada pedido entra uma vez por item. O total sai maior, plausível, e sem mensagem de erro. O MetricFlow, motor da camada semântica do dbt, ferramenta de transformação de dados, trata o problema pedindo o tipo de cada chave (primária, única ou estrangeira): a documentação traz a tabela de junções permitidas entre os tipos e marca como não permitidas as que causam fan-out, a multiplicação de linhas.

Sem ferramenta, o mínimo é uma lista de junções válidas com a cardinalidade de cada uma. O teste é de invariância e vale para métricas aditivas, aquelas cujo total é a soma das partes: o total tem de ser o mesmo com e sem a dimensão adicional. Se acrescentar categoria_produto altera a receita total, alguma junção está multiplicando ou descartando linhas. A exceção legítima é a dimensão muitos-para-muitos: com um produto em duas categorias, a soma das partes passa do total sem que haja erro.

Tempo e granularidade: calendário fiscal, data de referência e fechamento

Quase toda pergunta de analytics carrega uma data, em geral implícita. "Trimestre passado" exige saber se o calendário é civil ou fiscal. "Vendas de ontem" exige o fuso em que o dia vira: com Brasília três horas atrás do UTC, um warehouse que grava em UTC joga para o dia seguinte as vendas feitas a partir das 21h. "Resultado de setembro" exige saber se setembro já fechou.

Uma tabela de calendário, com período fiscal, dia útil e feriado para cada data, tira do modelo a tarefa de calcular datas. A data de referência declarada em cada métrica impede que ele escolha entre data_pedido, data_emissao_nf e data_pagamento por semelhança de nome. Uma marca de período fechado permite que a resposta avise quando o número ainda é parcial.

O grão temporal também é contexto. Saldo de estoque e carteira de crédito são fotografias, e somá-los ao longo dos dias do mês gera um valor sem significado. Por isso a definição do exemplo declara se a métrica é aditiva no tempo.

Regras de negócio e exceções: os filtros que ninguém escreve

Regra de negócio, aqui, é todo filtro que um analista experiente aplica sem pensar: excluir nota cancelada, descontar devolução, tirar venda entre empresas do mesmo grupo, ignorar o cliente de teste, desconsiderar a filial encerrada. Os autores do EntSQL classificaram 982 falhas de um dos modelos, o Qwen 3.6 Max, e 54,6% eram de filtro: condição obrigatória ausente, filtro redundante, valor de enumeração incorreto, coluna errada. É diagnóstico de um modelo só, como o próprio artigo ressalva, mas indica onde olhar.

-- Pergunta: "qual foi a receita de agosto?"
-- Esquema hipotético. As duas consultas executam sem erro.

-- A: o que o esquema sugere
SELECT SUM(valor_item)
FROM fato_nota_fiscal_item
WHERE data_emissao_nf >= DATE '2026-08-01'
  AND data_emissao_nf <  DATE '2026-09-01';

-- B: o que a controladoria chama de receita líquida
SELECT SUM(valor_item - impostos_venda - valor_devolvido)
FROM fato_nota_fiscal_item
WHERE data_emissao_nf >= DATE '2026-08-01'
  AND data_emissao_nf <  DATE '2026-09-01'
  AND status_nf = 'AUTORIZADA'
  AND tipo_operacao = 'VENDA'
  AND cliente_intragrupo = FALSE;

O esquema não oferece pista de que B é a consulta esperada, e A é a que um modelo competente escreveria com o que tem em mãos. A correção é embutir os filtros obrigatórios na definição da métrica, onde deixam de depender da memória de quem escreve o SQL. Exceções que não cabem em filtro, como a reclassificação de produtos em determinado mês, vão para um registro com motivo e data.

Permissões e o que o agente deve se recusar a responder

Permissão se aplica no banco, com a identidade de quem perguntou. O desenho que cria problema é o agente conectado por uma credencial de serviço de leitura ampla, com uma instrução no prompt dizendo quem pode ver o quê. Instrução em linguagem natural é um pedido ao modelo, sujeito a erro e a manipulação por quem redige a pergunta: a OWASP abre com a injeção de prompt a sua lista de riscos de aplicações com modelos de linguagem (LLM) de 2025. Políticas de linha (row-level security), regras com que o próprio banco decide quais linhas cada usuário enxerga, e políticas de coluna são avaliadas pelo banco em cada consulta, qualquer que seja o SQL gerado, desde que a credencial esteja sujeita a elas. No PostgreSQL, por exemplo, superusuários, papéis com o atributo BYPASSRLS e, por padrão, o dono da tabela ficam fora da política de linha.

A LGPD (Lei nº 13.709, de 2018) define dado pessoal como informação relacionada a pessoa natural identificada ou identificável, e tem entre seus princípios o da necessidade: tratamento limitado ao mínimo necessário para a finalidade. Num agente, isso vira decisão de desenho: quais colunas ele nem enxerga, se responde no nível do indivíduo, se a agregação tem tamanho mínimo de grupo, o que o log guarda. São sugestões de engenharia, sem pretensão de leitura jurídica; o enquadramento se define com o encarregado de dados e o jurídico de cada empresa.

A recusa é a sexta camada. Três situações pedem critério explícito: pergunta ambígua ("receita" sem qualificador), pergunta fora do escopo dos dados disponíveis e pergunta que exige um dado vetado. Nas três, pedir esclarecimento ou dizer que não sabe é a resposta certa.

Como entregar o contexto: camada semântica, catálogo ou recuperação?

Existem três mecanismos. Na camada semântica, o agente escolhe métricas e dimensões, e um compilador gera o SQL com a definição, os filtros e as junções declarados. No catálogo, ou esquema anotado, ele escreve SQL livre lendo descrições de tabelas e colunas. Na recuperação, trechos de documentação e consultas verificadas são selecionados conforme a pergunta. Só o primeiro garante algo por construção, e a escolha depende de quanto do contexto precisa ser garantia e quanto pode ser orientação.

Os três são alternativas a colar o manual inteiro na instrução, que funciona em demonstração e deixa ao modelo o trabalho de achar a regra pertinente. Uma combinação defensável usa camada semântica para as métricas oficiais e SQL livre com catálogo para exploração, e a resposta informa qual caminho a produziu.

Em qualquer dos três, a resposta deveria carregar a sua origem: o SQL executado, as tabelas lidas, a métrica e a versão da definição. Com a origem, o número pode ser conferido por amostragem. Sem ela, resta verificação integral ou fé, e um valor contestado em reunião não pode ser reconstruído.

Quanto o contexto melhora a acurácia do agente?

Entre 8 e 73 pontos percentuais nos estudos abertos para este artigo, com resultado final de 21% a 100%. A distância entre os extremos vem da dificuldade das perguntas, da forma de entregar o contexto e de quem mediu. Onde há comparação com e sem contexto, os resultados superiores a 90% vêm todos de quem construiu ou vende o sistema medido, em conjuntos de 11 a 150 perguntas.

Três medições não vêm de quem vende a tecnologia. O EntSQL, de 2026, já citado, é o ponto baixo: 21,4% com a evidência recortada. No BIRD, de 2023, a evidência escrita por especialistas para cada pergunta levou o GPT-4 de 34,88% a 54,89% de acurácia de execução, a fração de consultas cujo resultado coincide com o do gabarito. Em outubro de 2026 o topo do placar do BIRD está em 82,95%, contra 92,96% de humanos. Na GSK, em 2024, um documento de contexto escrito por especialistas levou o GPT-4 de 8,3% a 78,3% em 60 perguntas tiradas do histórico de usuários, num banco de mais de 500 tabelas, com julgamento de um especialista da casa.

Os números mais altos são de fornecedores de camada semântica ou de grafo de conhecimento: quem vende a camada mediu o ganho da camada. A data.world testou o GPT-4 em 43 perguntas sobre um esquema de seguros: 16,7% em SQL direto, 54,2% sobre um grafo de conhecimento do mesmo banco, em 2023, e 72% com verificação da consulta pela ontologia, em 2024. A AtScale reportou 92,5% contra 20% em 40 perguntas sobre o TPC-DS, em agosto de 2024. No mesmo mês, a Snowflake divulgou mais de 90% para o Cortex Analyst e 51% para o GPT-4o em prompt único, em 150 perguntas internas, sem isolar o efeito do modelo semântico.

O estudo que separa o que a camada com compilador cobre do que ela não cobre é o da dbt Labs, de abril de 2026: 11 perguntas sobre o esquema de seguros da data.world, cada uma executada 20 vezes. Nas cobertas, 100% com os dois modelos testados, contra 62,5% do SQL livre com o Claude Sonnet 4.6 e 51,2% com o GPT-5.3 Codex. Nas que ficavam de fora, 0%, com mensagem de erro no lugar de um número. Depois que três modelos de dados adicionais ampliaram a cobertura, 98,2% contra 90,0% e 100,0% contra 84,1%. O SQL livre recebeu o esquema inteiro como contexto, o que a própria dbt Labs diz não ser praticável em bancos maiores.

Os resultados baixos e os altos não se contradizem, porque medem perguntas diferentes: as do EntSQL pedem consultas longas, e as dos fornecedores ficam dentro do que a camada modelou. A GSK mostra que contexto bem escrito já leva longe sem compilador. O que a camada compilada acrescenta, nos dados da dbt Labs, é o modo de falhar: erro explícito onde o SQL livre devolveria um número plausível. Este artigo não localizou medição independente de uma camada semântica com compilador.

Dono, versão e teste: o contexto mantido como código

Contexto sem dono envelhece no ritmo das mudanças da empresa: um produto reclassificado, uma filial incorporada, uma regra de comissão nova. O tratamento que resiste é o mesmo que se dá a código.

1. Repositório. Definições de métrica, junções válidas, calendário e critérios de recusa ficam em arquivos versionados e mudam por revisão.
2. Dono por domínio. A área que responde pelo número responde pela definição: controladoria pela receita, crédito pela inadimplência.
3. Suíte de regressão. Perguntas com resposta conhecida rodam a cada alteração de contexto, de esquema ou de modelo. Compara-se o resultado da consulta; o texto do SQL pode variar.
4. Log por resposta. Pergunta, usuário, SQL, tabelas, métrica e versão do contexto. O acesso ao log segue a política dos dados, porque perguntas e resultados também podem conter dado pessoal.
5. Sinais de quebra. Mudança de esquema em tabela referenciada, métrica sem dono ativo, aumento de pedidos de esclarecimento e divergência entre o agente e o relatório oficial.

O desenho da suíte tem método próprio e fica fora deste inventário. Aqui importa o vínculo: cada uma das seis camadas precisa de pelo menos um teste, ou ninguém fica sabendo quando ela quebra.

Limitações e quando não usar esta abordagem

O inventário tem custo, e ele recai sobre pessoas que já têm outra função. Escrever a definição de receita obriga finanças e comercial a concordarem sobre ela, e essa negociação pode demorar mais do que a implementação. Sem esse acordo, o agente reproduz a divergência, com qualquer arquitetura.

Há contextos em que o esforço completo não se paga. Com poucas dezenas de tabelas, um punhado de métricas e um único time consumidor, o razoável é começar por um glossário curto e algumas consultas verificadas. Em análise exploratória, quando a pergunta ainda não tem métrica definida, uma camada semântica rígida atrapalha: o analista precisa de SQL livre e sabe conferir o resultado.

Um limite permanece mesmo com tudo implementado. O contexto reduz o erro de definição e deixa intacto o de interpretação: se a pergunta admite duas leituras e o agente escolhe uma sem avisar, a métrica certa responde à pergunta errada. E os números de benchmark deste artigo dão a direção, não a medida: a taxa de acerto no seu ambiente, só a sua suíte mede.

Perguntas frequentes

Referências técnicas

Fontes consultadas em 1º e 2 de outubro de 2026.

• Lei, F. et al. Spider 2.0. ICLR 2025. arXiv:2411.07763. Placar público
• Chen, P. B. et al. BEAVER. Versão 3, maio de 2026. arXiv:2409.02038
• Liao, C. et al. EntSQL. Versão 3, julho de 2026. arXiv:2606.03363
• Li, J. et al. BIRD. NeurIPS 2023. arXiv:2305.03111. Placar público
• Painter, J. L. et al. (GSK). Automating Pharmacovigilance Evidence Generation. 2024. arXiv:2406.10690
• Sequeda, J., Allemang, D. e Jacob, B. (data.world). 2023, arXiv:2311.07509; Allemang, D. e Sequeda, J. 2024, arXiv:2405.11706
• AtScale. Comunicado de 8 de agosto de 2024
• Huang, R. (Snowflake). Cortex Analyst: Evaluating Text-to-SQL Accuracy. 29 de agosto de 2024
• Ganz, J. e Perigaud, B. (dbt Labs). Semantic Layer vs. Text-to-SQL: 2026 Benchmark Update. 7 de abril de 2026
• dbt Labs. Documentação do MetricFlow: About MetricFlow e Joins
• PostgreSQL. Row Security Policies
• OWASP. LLM01:2025 Prompt Injection
• Brasil. Lei nº 13.709, de 2018 (LGPD), arts. 5º, I, e 6º, III. Texto atualizado, Câmara dos Deputados