Buscar K
Aparência
Fatos: Ensinando Seu Negócio
Um fato é a forma de explicar para o chat o que cada conceito do seu negócio significa na sua aplicação. É a peça que transforma uma resposta razoável em uma resposta consistente.
Em uma frase
Um fato é um exemplo de pergunta resolvida que você grava para o chat — você nomeia um conceito ("Faturamento") e mostra qual coluna é a métrica, em qual coluna o tempo é medido e que filtros padrão se aplicam.
A analogia do analista novo
Imagine que você está sentado no primeiro dia com um analista recém-contratado. Ele tem acesso ao seu modelo de dados, sabe ler tabelas e sabe escrever SQL. Em algum momento alguém entra na sala e pergunta:
"Qual o faturamento de ontem?"
O analista olha pra você confuso — no modelo tem três colunas que poderiam ser "faturamento": valor_bruto, valor_liquido e valor_pago. Tem duas colunas de data: data_emissao e data_competencia. E ele percebeu que vendas têm um status — "Confirmado", "Cancelado", "Pendente".
Você responde:
"Quando alguém aqui fala em Faturamento, é o Valor Líquido da tabela de vendas, considerando apenas o status Confirmado, com o tempo medido pela Data de Emissão."
Pronto. O analista agora sabe. Para a próxima pergunta — "faturamento do trimestre", "faturamento por filial", "faturamento ontem vs hoje" — ele aplica essa mesma definição variando apenas o que a pergunta variou.
É exatamente isso que um fato faz com o chat.
Por que o chat precisa de fatos
O chat consegue ver toda a estrutura da sua aplicação — tabelas, colunas, expressões, dashboards. Ele pode responder perguntas mesmo sem nenhum fato cadastrado.
O problema é a ambiguidade. Em modelos de dados reais quase sempre existe mais de uma resposta razoável:
- Múltiplas colunas que poderiam ser "vendas" (
valor_bruto,valor_liquido,valor_pago) - Múltiplas datas que poderiam ser "tempo" (emissão, competência, vencimento)
- Filtros sutis que mudam o resultado (
status = "Confirmado",tipo = "Comercial")
Sem fatos, o chat faz uma escolha razoável a cada conversa — mas a escolha não é determinística. Ele pode acertar hoje e errar amanhã na mesma pergunta, porque mais de um caminho parecia válido.
Um fato resolve isso sendo um exemplo curado: para este conceito de negócio na esta aplicação, a definição certa envolve estas colunas, esta data e estes filtros padrão.
Fato é definição, não relatório
Um fato grava uma definição que o chat usa como ponto de partida toda vez que aquele conceito aparece numa pergunta — independente das variações. "Faturamento do trimestre", "faturamento por filial" e "faturamento ontem vs hoje" são todas a mesma definição com agrupamentos e recortes diferentes. Você define uma vez; o chat aplica em todas as perguntas que tocam o conceito.
Como criar um fato
Os fatos vivem dentro do editor da aplicação, na aba Conceitos IA.
- Abra a aplicação no modo de edição (ícone de lápis no menu superior).
- Acesse a aba Conceitos IA.
- Há dois caminhos:
Manualmente — botão "Novo Insight"
Você preenche os campos diretamente (Nome, Valor Principal, Coluna de Data, etc.). Use quando já sabe exatamente o que quer cadastrar.
Automaticamente — botão "Gerar Insight Automaticamente"
Você descreve em linguagem natural ("faturamento líquido considerando apenas vendas confirmadas, com tempo medido pela data de emissão"). A IA sugere a configuração, você revisa, ajusta se precisar e salva.
TIP
O modo automático é ótimo para popular os primeiros fatos da aplicação rapidamente. Mas sempre revise — em modelos ambíguos, a sugestão pode escolher uma coluna parecida em vez da que você quer.
Para a referência detalhada da UI (formulário, duplicar, expandir, excluir), veja Aba Conceitos IA.
Os campos em detalhe
Cada fato é descrito por um pequeno conjunto de campos. Entender o propósito de cada um é o que separa um fato bom de uma definição vaga.
Nome (obrigatório)
O termo que as pessoas da sua empresa de fato usam quando falam desse conceito. Em português, sem jargão técnico.
✅ "Faturamento", "Ticket Médio", "Inadimplência", "Pedidos em Aberto"
❌ "SUM_VLR_LIQ", "FAT_2024", "Vendas_Mensal_Por_Filial"O nome é o sinal mais forte que o chat usa para identificar quando aplicar o fato. Se você o nomear "Vendas" mas a sua empresa fala "Faturamento", o fato perde valor.
Prompt (opcional)
Texto livre com a nuance do conceito. Use para diferenciar conceitos parecidos ou registrar uma regra de negócio sutil que o nome sozinho não carrega:
Prompt: "Faturamento comercial. Considera apenas vendas confirmadas
do canal direto. Não inclui receita financeira (juros, multas)."O prompt não substitui um fato novo
Se o prompt está crescendo a ponto de "explicar dois conceitos diferentes em um só fato", isso é sinal de que você precisa de dois fatos, não de um prompt maior.
Valor Principal (obrigatório)
A coluna ou expressão que representa a métrica desse conceito. Tem que ser uma medida — algo que se soma, conta ou agrega.
Valor Principal: [Fato Vendas]."VALOR_LIQUIDO" (soma)Valores Alternativos (opcional, mas muito importante)
Outras métricas que compartilham o mesmo contexto desse fato — mesma tabela, mesma data, mesmos filtros. É aqui que você evita criar fatos redundantes.
Exemplo: o fato "Faturamento" tem Valor Líquido como principal, e Lucro, Margem (%), Ticket Médio e Quantidade Vendida como alternativos. Quando alguém pergunta "qual o ticket médio do mês?", o chat usa o mesmo fato Faturamento, só troca a métrica.
Coluna de Data (opcional, mas quase sempre presente)
A coluna usada quando a pergunta envolve tempo. Sem ela, "faturamento do mês passado" não tem ancoragem temporal e o chat precisa adivinhar entre as datas disponíveis.
Coluna de Data: [Calendário]."DATA" (mapeada para Data de Emissão)Filtros Padrão (opcional)
Contexto fixo que sempre se aplica a esse conceito. Use quando o conceito tem uma regra de negócio que não pode ser esquecida.
Filtros Padrão: Status = "Confirmado"Sem esse filtro, "faturamento" passaria a incluir vendas canceladas e pendentes — distorcendo todas as respostas. Filtros padrão são a forma de garantir que o conceito chega íntegro em qualquer pergunta.
Comportamento que você precisa entender
Esse é o ponto onde a maioria das pessoas se enrosca, então vale entender devagar:
Todos os fatos da aplicação são carregados em cada conversa
Quando alguém abre uma conversa com o chat sobre uma aplicação, o catálogo inteiro de fatos daquela aplicação entra junto como contexto. O chat olha pra esse catálogo e escolhe os fatos relevantes pra responder.
Esse comportamento tem uma consequência direta:
- Poucos fatos bem definidos → o chat olha 10 ou 20 cartas na mesa, identifica rapidamente o conceito certo, responde com clareza.
- Muitos fatos parecidos → o chat precisa filtrar entre centenas de opções similares. Ele gasta mais tempo decidindo, pode misturar definições de fatos próximos e tende a alucinar mais.
Em outras palavras: excesso de fatos piora o chat. A qualidade sobe com fatos curados e cai quando o catálogo vira um inventário pulverizado.
Custo cresce junto com o catálogo
Esse mesmo catálogo entra no processamento a cada mensagem da conversa — incluindo respostas triviais como "oi, bom dia" ou "obrigado". Em uma aplicação com centenas de fatos cadastrados, mesmo um simples cumprimento puxa o catálogo inteiro pra dentro do turno, o que se traduz em consumo de tokens (e custo) muito maior por interação. Catálogos enxutos não só respondem melhor — respondem mais barato.
O anti-padrão "dicionário gigante"
A intuição errada mais comum é: "quanto mais fatos eu cadastrar, melhor o chat fica". É o oposto. Quando o catálogo passa de algumas dezenas, o chat perde foco — passa a hesitar entre opções parecidas e mistura definições.
Padrões a evitar
| Padrão errado | Por quê é ruim |
|---|---|
| Criar um fato para cada variação de pergunta ("Vendas", "Vendas Mensais", "Vendas por Filial", "Vendas Ontem"…) | Todas são a mesma definição de "Vendas". Agrupamento, período e recorte são como o chat usa o fato, não definições novas. |
| Criar um fato por dimensão de quebra ("Receita por Cliente", "Receita por Produto", "Receita por Cidade"…) | A dimensão é decidida pela pergunta. Um fato "Receita" cobre todas. |
| Replicar o mesmo fato com filtros temporais diferentes ("Faturamento de 2024", "Faturamento Mensal", "Faturamento Diário") | Filtro de tempo o chat aplica sozinho. O recorte temporal pertence à pergunta, não à definição. |
| Criar um fato para cada métrica relacionada quando elas compartilham o mesmo contexto (mesma data, mesmos filtros) | Use o campo Valores Alternativos dentro de um fato. Um fato "Faturamento" pode listar Lucro, Margem, Ticket Médio, Quantidade como alternativos. |
O nome "dicionário gigante" é literal: cada possível pergunta vira um verbete. O catálogo cresce sem parar, fica difícil de manter, e o chat fica pior, não melhor.
Sinais de mau dimensionamento
Alguns sinais práticos de que o catálogo está virando dicionário gigante:
- Mais de 50 fatos numa única aplicação. Tipicamente um app de negócio tem entre 5 e 25 conceitos genuinamente diferentes. Acima de 50 quase sempre indica pulverização.
- Você consegue agrupar fatos em "famílias" óbvias. Se cinco fatos da lista são "Vendas X", "Vendas Y", "Vendas Z" — provavelmente é um único fato "Vendas" com Valores Alternativos e a dimensão variando na pergunta.
- Dois fatos têm a mesma Valor Principal, mesma Coluna de Data, mesmos Filtros Padrão. São o mesmo fato com nomes diferentes. Consolide.
- Existem fatos cujo nome só faz sentido para quem cadastrou. Se ninguém na empresa fala assim no dia a dia, ninguém vai perguntar assim — e o fato vira ruído.
- As respostas do chat ficaram inconsistentes depois que o catálogo cresceu. É sintoma de excesso de fatos parecidos competindo entre si.
Heurística
Se você tem mais de 50 fatos numa única aplicação, provavelmente está virando catálogo telefônico. Vale auditar.
Boas práticas
Pergunte antes: "quantos conceitos genuinamente diferentes existem aqui?"
Tipicamente são 5 a 25 por aplicação. Faça a lista no papel primeiro, depois cadastre. Comece pelos conceitos que as pessoas perguntam, não pelos que existem no banco.
Um fato = um conceito de negócio
A pergunta-teste: se duas pessoas diferentes da empresa, ao ouvir o nome do fato, descrevem a mesma métrica, é um conceito. Se elas descrevem coisas ligeiramente diferentes, talvez sejam dois fatos genuínos — ou talvez seja um conceito mal nomeado.
Agrupe métricas relacionadas em "Valores Alternativos"
Se cinco métricas (Receita, Lucro, Margem, Ticket Médio, Quantidade) compartilham mesma data, mesma tabela, mesmos filtros padrão, são um único fato com cinco valores. Não cinco fatos.
Use o campo Prompt para nuance, não para criar outro fato
Se a diferença entre dois fatos é uma frase ("este desconsidera estornos"), o Prompt do fato resolve. Se a diferença é genuína (tabelas diferentes, datas diferentes, filtros diferentes), então sim, são dois fatos.
Cuide do nome
Linguagem que sua empresa de fato usa, em português, sem siglas técnicas. O nome do fato é o canal pelo qual a IA reconhece "esta pergunta é sobre este conceito" — se o nome não bate com o vocabulário da empresa, o fato passa despercebido.
Revise periodicamente
- Se um fato nunca é usado, remova ou consolide.
- Se dois fatos sempre são chamados juntos na mesma pergunta, consolide num só com Valores Alternativos.
- Se o chat erra consistentemente em algum conceito, o fato relacionado pode estar mal definido (coluna errada, filtro faltando).
Quando estiver na dúvida, menos é mais
Você sempre pode adicionar um fato novo depois. É muito mais difícil descobrir que o catálogo cresceu demais e ter que limpar 400 fatos.
Próximos passos
- Veja Exemplos de Fatos para casos práticos lado a lado: fatos bem feitos vs anti-exemplos do "dicionário gigante".
- Entenda Como o chat responde para ver onde os fatos entram no processo de uma pergunta.
- Consulte a Aba Conceitos IA para a referência detalhada da UI (formulário, duplicar, expandir, excluir).