Computed traits — conceitos, regras e casos de uso

Computed traits transformam eventos em informações úteis no perfil. Uma regra pode guardar um valor, contar ocorrências, calcular uma média, manter o maior ou o menor valor e formar uma coleção sem exigir que o campo esteja declarado na definição do evento.

Um computed trait é uma boa escolha quando a informação precisa de condição, transformação ou memória. Ele também atende integrações com eventos de alta cardinalidade, nas quais apenas os campos mais previsíveis foram declarados e as demais propriedades passaram a aparecer no catálogo depois da ingestão.

Computed traits produzem traits no perfil. Eles não usam outros traits como entrada: cada cálculo parte do evento que acionou a regra, de um valor fixo ou do estado anterior do próprio trait quando a operação é acumulativa.

Quando usar um computed trait

Use um computed trait para responder perguntas como:

• qual foi o valor da última compra desta pessoa;
• quantas compras ela fez;
• qual é o seu ticket médio;
• quais categorias de produto ela já comprou;
• qual foi o maior valor já observado;
• se a última forma de pagamento atendia a uma condição.

Para copiar diretamente um campo declarado por uma definição bem estruturada, prefira um trait mapping. O mapping deixa explícito no contrato qual campo atualiza o perfil. O computed trait é mais adequado quando existe uma regra de negócio ou quando o campo só está disponível no catálogo de propriedades.

Como uma regra funciona

Uma regra combina:

1. o nome e a versão exatos do evento que ela acompanha;
2. filtros opcionais;
3. a origem do valor, que pode ser um caminho do evento ou um valor fixo;
4. uma operação;
5. normalizações opcionais;
6. a chave e o tipo do trait que serão atualizados.

Quando chega um evento compatível, o PrismaFlow avalia os filtros. Se todos passarem, extrai e normaliza o valor, executa a operação e atualiza o perfil quando há um resultado válido.

Uma regra criada para purchase v1 não acompanha automaticamente purchase v2. Ao publicar uma nova versão do evento, revise também os computed traits, segmentos e jornadas que dependem da versão anterior.

Filtros não representam verdadeiro e falso

Um filtro decide se a regra deve continuar. Quando ele não passa, a regra para ali: ela não grava false, não limpa o trait e não desfaz uma atualização anterior.

Imagine o trait ultima_compra_foi_pix. Uma regra que filtra payment_method = PIX e grava true funcionará na primeira compra por PIX. Porém, uma compra posterior por cartão não fará essa regra gravar false; o filtro apenas deixará de passar e o valor antigo continuará no perfil.

Para representar um estado reversível, modele os dois caminhos:

• se payment_method = PIX, grave true;
• se payment_method != PIX, grave false.

Se a propriedade estiver ausente ou nula, nenhum desses caminhos precisa avançar. Nesse caso, o último estado válido continua no perfil. Antes de usar um filtro, pergunte se o silêncio da regra é realmente o comportamento desejado.

Uma regra pode ter várias condições. Todas precisam passar para que o cálculo continue.

De onde vem o valor

O valor pode ser fixo ou extraído de um caminho do evento. Os caminhos podem apontar para propriedades enviadas pelo cliente ou para informações de contexto disponibilizadas pela integração.

Também é possível selecionar uma posição de uma lista. Imagine que properties.coordinates chegue como [-23.5505, -46.6333], no formato [latitude, longitude]. Uma regra pode selecionar o índice 0 para guardar a latitude, enquanto outra seleciona o índice 1 para guardar a longitude. Se o caminho não existir, o índice estiver fora da lista ou o valor não puder ser convertido para o tipo esperado, aquela ocorrência não atualiza o trait.

Valores fixos são especialmente úteis para estados booleanos, como gravar true depois de um evento de aprovação, ou para contar eventos somando 1 a cada ocorrência.

Operações disponíveis

Definir (set)

Substitui o valor atual pelo novo valor.

Exemplos: última cidade informada, último produto visto ou se a última compra usou PIX.

O resultado é o mesmo de um trait mapping: um valor do evento passa a representar o estado atual do perfil. Uma opção não anula a outra; são duas formas de produzir o mesmo tipo de atualização.

Quando o campo está declarado em uma definição bem estruturada e pode ser copiado diretamente, o trait mapping costuma ser o caminho mais simples. Use set em um computed trait quando o campo vem do catálogo de propriedades, precisa passar por filtros ou transformações, ou quando um valor fixo deve ser gravado.

Último valor (last)

Mantém o valor da ocorrência mais recente processada pela regra.

Exemplos: último valor de compra ou última categoria visitada.

Primeiro valor (first)

Guarda o primeiro valor válido e não o substitui nas ocorrências seguintes.

Exemplos: primeiro canal de aquisição ou primeira categoria comprada.

Incrementar (increment)

Soma o valor recebido ao estado atual. Quando o trait ainda não existe, o cálculo começa em zero.

Usar o valor fixo 1 permite contar ocorrências, como total_de_compras. Usar uma propriedade numérica permite acumular valores, como valor_total_comprado.

Média (avg)

Calcula a média acumulada dos valores observados e apresenta o resultado com até duas casas decimais.

Exemplo: calcular ticket_medio a partir de properties.amount em cada compra.

Maior e menor (max e min)

Mantêm, respectivamente, o maior ou o menor valor válido já observado.

Exemplos: maior compra realizada ou menor temperatura registrada por um dispositivo.

Colecionar (collect)

Cria uma lista sem valores repetidos. A coleção mantém até 200 itens.

Exemplos: categorias já compradas, lojas visitadas ou canais utilizados.

Transformações em camadas

Antes da operação, uma regra pode aplicar várias transformações ao valor. Elas acontecem na ordem configurada, e cada etapa recebe o resultado da anterior.

Imagine que properties.full_name chegue como JANE DOE, mas o perfil precise guardar apenas o primeiro nome:

1. a regra lê JANE DOE;
2. a transformação de primeira palavra produz JANE;
3. a capitalização produz Jane;
4. a operação grava Jane no trait first_name.

Esse encadeamento permite criar uma pequena camada de preparação do dado dentro da própria regra. Entre as transformações disponíveis, é possível:

• remover espaços extras;
• converter texto para maiúsculas, minúsculas ou formato de título;
• selecionar a primeira ou a última palavra;
• converter texto numérico usando ponto ou vírgula decimal;
• usar o valor absoluto;
• arredondar de zero a dez casas decimais.

Depois da última transformação, o resultado ainda precisa ser compatível com o tipo escolhido para o trait. Números enviados como texto, como "10", podem ser convertidos para 10. Os textos "true" e "false" podem formar valores booleanos. Datas precisam ser válidas.

As transformações ajudam a lidar com formatos conhecidos; elas não devem esconder uma integração imprevisível. Se os valores chegam em formatos muito diferentes, corrija a fonte ou modele regras separadas e fáceis de entender.

Mais de uma regra para o mesmo trait

É comum ter várias regras escrevendo na mesma chave. Um cliente pode, por exemplo, atualizar ultima_interacao a partir de eventos diferentes ou criar regras complementares para os estados true e false.

Isso também ajuda quando a própria integração separa um acontecimento em eventos diferentes. Imagine que ela envie COMPRA_PIX, COMPRA_CARTAO e COMPRA_BOLETO, sem um evento geral PURCHASE com a propriedade payment_method.

Nesse caso, três regras podem escrever em ultimo_metodo_de_pagamento: a primeira grava PIX, a segunda CARTAO e a terceira BOLETO. Se o objetivo for conhecer todos os métodos já utilizados, as três regras também podem alimentar uma coleção como metodos_de_pagamento_utilizados.

As regras compartilham a chave, mas não disputam a mesma ocorrência, porque cada uma acompanha um evento diferente. Esse tipo de composição é útil quando a informação está representada pela existência do evento, e não por uma propriedade dentro dele.

A prioridade ajuda a organizar um catálogo grande e expressar quais regras são mais importantes. Na maior parte dos casos, regras ligadas a eventos ou condições diferentes não disputam a mesma ocorrência.

Existe uma colisão quando duas ou mais regras ativas acompanham o mesmo nome e versão de evento, escrevem no mesmo trait e têm filtros que passam ao mesmo tempo. Nessa situação, somente a regra de maior prioridade é escolhida. Por isso, não use prioridades para esconder condições ambíguas: torne os filtros mutuamente exclusivos sempre que possível.

Se a regra escolhida encontrar depois um valor ausente ou inválido, outra regra de prioridade menor não assume seu lugar naquela ocorrência.

Alterar, pausar ou remover uma regra

As mudanças afetam os eventos processados dali em diante:

• pausar uma regra interrompe novas avaliações;
• editar uma regra muda os próximos cálculos;
• remover uma regra impede novas atualizações.

Nenhuma dessas ações apaga automaticamente o valor que já está no perfil. Se a nova modelagem precisa corrigir dados anteriores, avalie um backfill.

Evite alterar regras acumulativas sem revisar o efeito sobre o estado existente. Mudar a origem ou o significado de uma contagem, soma ou média no meio da operação pode misturar dois cálculos diferentes no mesmo trait.

Backfill: recalcular o passado

O backfill aplica regras de computed traits a eventos históricos. Ele é útil quando uma regra nasce depois da integração. Se compras já são recebidas há meses e agora é preciso calcular o ticket médio, o backfill percorre o período desde o início escolhido até o fim e refaz o cálculo em ordem cronológica.

O reprocessamento é silencioso por segurança. Ele atualiza os traits e a visão atual dos perfis, mas:

• não emite as atualizações usadas para acionar jornadas;
• não reavalia segmentos incrementais durante o processamento;
• não registra no histórico de traits as alterações produzidas pelo reprocessamento.

Essa proteção importa porque uma única execução pode afetar milhares de perfis. Imagine uma jornada que concede R$ 10 quando um trait muda. Dispará-la durante um recálculo histórico poderia incluir uma audiência inteira por acidente.

Quando o objetivo for usar os perfis recalculados em uma ação, o caminho recomendado é controlado: conclua o backfill, crie um segmento agendado e inicie uma jornada também agendada com aquela audiência.

Cada execução aceita um intervalo de até 306 dias e não processa as 24 horas mais recentes. Para um histórico maior, planeje janelas sequenciais e confira o resultado entre elas.

Não edite, pause ou remova as regras envolvidas enquanto um backfill estiver em andamento. A execução usa o estado corrente das regras ao processar cada parte do período, e uma mudança no meio do trabalho pode produzir um resultado misto.

Exemplos de modelagem

Antes de ativar uma regra

1. Escreva a pergunta que o trait deve responder.
2. Confirme o nome e a versão do evento.
3. Confira se a propriedade e seu tipo já aparecem no catálogo.
4. Decida o que deve acontecer quando um filtro não passar.
5. Modele o caminho reverso quando o estado puder voltar de true para false.
6. Verifique se outra regra pode disputar a mesma ocorrência e o mesmo trait.
7. Escolha uma operação que continue correta depois de meses de eventos.
8. Planeje o backfill e a ativação da audiência separadamente quando precisar do histórico.

Assuntos relacionados

• Traits e evolução do perfil
• Eventos, definições e propriedades

Revisão editorial

• Estado: Em revisão
• Fatos confirmados em: implementação atual das regras, execução online, Customer 360 e backfill
• Walkthrough: conhecimento operacional fornecido pelo Darlysson na PF-1367 em 15/08/2026
• Lacunas conhecidas: findings técnicos registrados no complemento interno