Segmentos — cláusulas, combinações e modelagem

Uma boa modelagem começa com uma frase de negócio e termina com condições que preservam exatamente o significado dessa frase. Trocar “nunca fez” por “fez uma vez sem”, por exemplo, pode criar uma audiência completamente diferente.

Este guia apresenta as cláusulas disponíveis, explica como combiná-las e mostra armadilhas comuns. Para entender estados, modos e ativação, consulte Segmentos — fundamentos, criação e ciclo de vida [blocked].

Grupos de condições

As cláusulas podem ser organizadas em três tipos de grupo.

E (AND)

Todas as condições precisam ser verdadeiras.

Exemplo: plano atual é premium E cidade atual é Recife.

OU (OR)

Pelo menos uma condição precisa ser verdadeira.

Exemplo: categoria favorita é livros OU categoria favorita é papelaria.

NÃO (NOT)

Inverte uma condição ou um grupo filho.

No construtor, esse grupo aparece quando a estrutura possui uma condição positiva de evento capaz de definir o universo da pesquisa.

Exemplo: realizou uma compra E NÃO realizou uma compra com cupom.

Use grupos aninhados quando a frase exigir parênteses:

plano é premium E (cidade é Recife OU cidade é Olinda).

Não dependa apenas da posição visual das condições. Leia o grupo como uma frase e confira quais partes precisam ser verdadeiras juntas.

Trait atual

Compara o valor atual de um trait do perfil.

Use para perguntas como:

• o plano atual é premium;
• a cidade atual está numa lista de capitais;
• o limite disponível é maior que 1.000;
• o trait first_name existe.

Essa cláusula consulta estado, não histórico. Se o plano já foi premium, mas hoje é basic, a condição “plano atual é premium” não passa.

Os operadores disponíveis dependem do tipo do trait:

• igualdade e diferença;
• está ou não está numa lista;
• maior, maior ou igual, menor e menor ou igual;
• contém;
• existe.

Um campo ausente ou nulo não passa em “não é” nem em “não está na lista”. Esses operadores comparam valores existentes; eles não significam “o campo não existe”. Não substitua uma condição de ausência por uma comparação negativa. Quando a ausência for parte do negócio, represente-a por um estado explícito ou confirme se a estrutura disponível permite negar a condição existe.

Cuidado ao comparar um trait com zero

O PrismaFlow não cria um valor inicial para um trait que ainda será calculado. Imagine um computed trait chamado total_compras, incrementado em 1 a cada pedido. Antes da primeira compra, esse trait não vale 0: ele ainda não existe. Quando for criado, seu primeiro valor já será 1.

Por isso, um segmento com total_compras = 0 não encontra quem nunca comprou. A regra compara apenas traits existentes e não transforma ausência em zero.

Escolha a condição pela pergunta:

• para saber se a pessoa já possui aquele estado calculado, use existe;
• para saber se uma ação aconteceu, prefira “evento ocorreu”;
• para saber se nunca aconteceu ou se a contagem é zero, use uma cláusula de evento negativa ou uma contagem de eventos igual a zero, acompanhada de uma âncora positiva.

Só compare um trait com 0 quando zero for um valor real que pode ser gravado naquele trait, e não uma tentativa de representar um valor que ainda não existe.

Trait mudou

Procura mudanças de um trait dentro de uma janela de 1 a 365 dias.

É possível filtrar:

• apenas o valor novo;
• apenas o valor anterior;
• os valores anterior e novo ao mesmo tempo;
• qualquer mudança daquela chave, sem filtrar valores.

Exemplo: encontrar pessoas cujo plano mudou de basic para premium nos últimos 7 dias.

Essa cláusula procura uma transição no histórico. Se o perfil mudou de basic para premium e depois para enterprise, a primeira transição continua podendo satisfazer a regra enquanto estiver dentro da janela, mesmo que premium já não seja o valor atual.

Quando o estado atual também importa, combine as duas ideias:

plano mudou de basic para premium nos últimos 7 dias E plano atual ainda é premium.

Evento ocorreu

Verifica se o perfil possui pelo menos uma ocorrência do nome e da versão escolhidos dentro da janela.

Exemplos:

• realizou PURCHASE v1 nos últimos 30 dias;
• concluiu SIGN_UP v2 nos últimos 7 dias;
• recebeu PAYMENT_DECLINED v1 hoje.

Filtros opcionais restringem quais ocorrências contam. “Realizou uma compra por PIX”, por exemplo, procura uma ocorrência de PURCHASE cujo properties.payment_method seja PIX.

Todos os filtros colocados dentro da mesma cláusula precisam passar na mesma ocorrência do evento.

Contagem de eventos

Conta quantas ocorrências compatíveis existem dentro da janela e compara o total com um número inteiro.

Exemplos:

• realizou pelo menos 3 compras nos últimos 30 dias;
• concluiu um cadastro e teve exatamente 0 recusas nos últimos 7 dias;
• abriu o aplicativo mais de 10 vezes no mês.

Use a contagem quando a quantidade de ocorrências importa. Para saber apenas se houve pelo menos uma, “evento ocorreu” costuma expressar a intenção com mais clareza.

Filtros também participam da contagem. “Pelo menos 3 compras acima de R$ 100” conta apenas as compras cujos dados passam pelo filtro configurado.

Uma comparação de contagem que aceita zero também é negativa e precisa de uma âncora positiva no mesmo grupo E, assim como “evento não ocorreu”.

Evento não ocorreu

Verifica que nenhuma ocorrência compatível foi encontrada dentro da janela.

Uma condição negativa precisa de uma condição positiva no mesmo grupo E. Sem uma âncora, “quem não comprou” não informa qual universo de perfis deve ser pesquisado.

Exemplo: comprou, mas nunca usou cupom

Imagine a audiência “clientes que fizeram compras, mas nunca utilizaram cupom nos últimos 365 dias”. Modele duas cláusulas sobre o mesmo evento:

1. PURCHASE v1 ocorreu nos últimos 365 dias, sem filtros;
2. PURCHASE v1 não ocorreu nos últimos 365 dias com properties.coupon_applied = true.

Una as duas com E:

fez pelo menos uma compra E não existe compra com cupom.

A primeira cláusula ancora o universo em pessoas que realmente compraram. A segunda exclui qualquer pessoa que tenha ao menos uma compra com cupom.

Usar apenas “compra ocorreu com coupon_applied != true” não produz o mesmo resultado. Essa versão prova somente que houve uma compra sem cupom. A mesma pessoa ainda poderia ter outra compra com cupom e continuaria na audiência.

Esse padrão é útil para frases como:

• realizou a ação, mas nunca por determinado canal;
• utilizou o produto, mas nunca uma funcionalidade específica;
• concluiu pedidos, mas nunca escolheu entrega expressa.

Agregação de eventos

Calcula soma, média, máximo ou mínimo de uma propriedade numérica dentro da janela e compara o resultado com um valor.

Exemplos:

• soma das compras nos últimos 30 dias maior ou igual a R$ 1.000;
• média das compras no trimestre maior que R$ 150;
• maior compra do mês acima de R$ 500;
• menor saldo observado nos últimos 7 dias abaixo de R$ 50.

Os filtros são aplicados antes do cálculo. É possível, por exemplo, somar apenas compras de uma categoria ou por um meio de pagamento específico.

Use agregação no segmento quando a pergunta depende de uma janela daquela audiência. Use um computed trait quando o cálculo precisa se tornar um estado reutilizável no perfil ou ser compartilhado por várias modelagens.

Funil de eventos

Verifica uma sequência ordenada de eventos dentro da janela configurada.

Um funil pode representar:

1. cadastro concluído;
2. produto visualizado;
3. produto adicionado ao carrinho;
4. compra realizada.

Você pode exigir todas as etapas ou uma profundidade mínima. Com quatro etapas e profundidade 3, passam os perfis que completaram pelo menos as três primeiras na ordem esperada. Com profundidade 4, apenas quem concluiu todo o funil passa.

Cada etapa pode ter seus próprios filtros. A ordem importa: possuir os quatro eventos fora da sequência não equivale a completar o funil.

Pertence a outro segmento

Usa a membership materializada de outro segmento como condição.

Isso permite reutilizar uma audiência já conhecida em vez de repetir todas as suas regras. Um segmento pode, por exemplo, partir da lista de clientes de alto engajamento.

Evite cadeias difíceis de acompanhar. Quando um segmento depende de outro, uma entrada ou saída na lista de origem pode provocar a reavaliação do segmento dependente. Nomes e descrições claros ajudam a entender essa cascata.

Combinações entre memberships e outras fontes ainda passam por uma conciliação para garantir o mesmo resultado na prévia, no tempo real e na recomputação. Até essa revisão ser concluída, prefira uma única condição de membership ou confirme cuidadosamente cada caminho antes do uso operacional.

Filtros dentro de eventos

Filtros de evento consultam campos de properties ou context da combinação exata de nome e versão.

As opções da interface vêm da definição do evento. Atualmente, o caminho aceita um campo direto, como properties.amount ou context.device_type; campos aninhados em vários níveis não fazem parte desse contrato.

Até 10 filtros podem ser usados numa mesma cláusula ou etapa de funil. Todos são combinados com E e precisam passar na mesma ocorrência.

Os principais operadores são:

• é e não é;
• está em e não está em;
• maior, maior ou igual, menor e menor ou igual;
• contém;
• existe.

Um valor ausente não passa em comparações negativas como “não é” ou “não está em”. Isso evita incluir silenciosamente eventos que nem sequer possuem o campo comparado.

Escolha a cláusula pela pergunta

Limites atuais

Uma definição aceita:

• até 50 nós no total;
• até 5 níveis de grupos;
• até 20 cláusulas de trait atual;
• até 10 cláusulas baseadas em eventos;
• até 10 cláusulas de mudança de trait;
• até 5 cláusulas de membership;
• até 10 filtros por cláusula de evento;
• de 2 a 10 etapas por funil;
• janelas de 1 a 365 dias;
• até 100 valores nos operadores está em e não está em.

Os limites protegem a leitura e a execução da regra. Quando uma audiência se aproxima deles, considere criar segmentos menores e reutilizáveis, desde que a composição continue simples de investigar.

Antes de publicar

1. Leia a árvore como uma frase de negócio.
2. Confirme onde os parênteses de E, OU e NÃO começam e terminam.
3. Diferencie estado atual de mudança histórica.
4. Confirme nome e versão de cada evento.
5. Verifique se todos os filtros de uma cláusula devem acontecer na mesma ocorrência.
6. Para uma condição negativa de evento, inclua uma âncora positiva no mesmo grupo E.
7. Diferencie “teve uma ocorrência sem X” de “nunca teve uma ocorrência com X”.
8. Confira se a passagem do tempo exige um segmento agendado [blocked].
9. Compare prévia, avaliação incremental e recomputação quando combinar fontes diferentes.

Assuntos relacionados

• Segmentos — fundamentos, criação e ciclo de vida [blocked]
• Segmentos — avaliação, membership e operação [blocked]
• Traits e evolução do perfil
• Computed traits — conceitos, regras e casos de uso

Revisão editorial

• Estado: Em revisão
• Fatos confirmados em: DSL, compilador, mecanismos de avaliação e dashboard atuais
• Walkthrough: conhecimento operacional fornecido pelo Darlysson na PF-1369 em 15/08/2026
• Lacunas conhecidas: equivalência de combinações entre fontes nos caminhos de prévia, avaliação incremental e recomputação