Extensões de Segment do SQL
Você pode gerar uma extensão de Segment usando consultas de SQL do Snowflake de dados do Snowflake. O SQL pode ajudar a desbloquear novos casos de uso de segmentos porque oferece a flexibilidade de descrever as relações entre os dados de maneiras que não são possíveis por meio de outros recursos de segmentação.
Assim como as extensões de Segment padrão, você pode consultar eventos dos últimos dois anos (730 dias) na sua extensão de Segment SQL. Diferentemente das extensões de Segment padrão, as extensões de Segment SQL consomem créditos.
Pré-requisitos
Para usar extensões de segmento SQL, você precisa destas permissões no seu espaço de trabalho:
| Permissão | O que ela permite |
|---|---|
| “View Segments” | Abrir extensões de segmento e visualizar extensões de segmento SQL |
| “Edit Segments” | Criar, editar e atualizar extensões de segmento SQL |
| “View PII” | Executar consultas de prévia em SQL que podem retornar dados de cliente |
Criar uma extensão de segmento
Etapa 1: Escolha um editor
Ao criar sua extensão de segmento SQL, você pode escolher entre dois tipos de editor de SQL: o Editor de SQL e o Editor de SQL incremental.
- Atualização completa: A cada atualização do seu Segment, a Braze consulta todos os dados disponíveis para atualizá-lo. Isso usa mais créditos do que as atualizações incrementais. Extensões com atualização completa podem regenerar a associação automaticamente todos os dias, mas não podem usar a atualização incremental.
- Atualização incremental: A atualização incremental é uma forma mais econômica de configurar sua consulta, embora a configuração exija algumas etapas a mais. Se você conseguir concluir essas etapas adicionais ao construir seu Segment, vale a pena escolher essa opção, porque sua consulta usa menos créditos.
Para que o Operator escreva o SQL para você, selecione Perguntar ao Operator em qualquer um dos editores e descreva seu público em linguagem simples. Para saber mais, consulte O que você pode fazer com o Operator.

Você pode fazer uma atualização completa manual em todos os Segments SQL criados em qualquer um dos editores de SQL.
Para criar uma extensão de segmento SQL com atualização completa:
- Acesse Público > Extensões de segmento.
- Selecione Criar nova extensão e, em seguida, selecione Atualização completa.

- Adicione um nome para sua extensão de segmento e insira seu SQL. Consulte a Etapa 2 para ver os requisitos e recursos.

- Salve sua extensão de segmento.
Para criar uma extensão de segmento SQL com atualização incremental:
- Acesse Público > Extensões de segmento.
- Selecione Criar nova extensão e selecione Atualização incremental.

- Adicione um nome para sua extensão de segmento e insira seu SQL. Consulte a Etapa 2 para ver os requisitos e recursos.

- Se quiser, selecione Regenerar extensão diariamente.

Quando essa opção está selecionada, a Braze atualiza automaticamente a associação ao Segment todos os dias. Ou seja, todos os dias à meia-noite no fuso horário da sua empresa (com possível postergação de até uma hora), a Braze verifica se há novos usuários no seu Segment e os adiciona automaticamente. Se uma extensão de segmento não for usada por 7 dias, a Braze pausa automaticamente a regeneração diária. Uma extensão de segmento não utilizada é aquela que não faz parte de nenhuma Campaign ou Canvas (a Campaign ou o Canvas não precisa estar ativo para que a extensão seja considerada “usada”). - Salve sua extensão de segmento.

Consultas de SQL que levam mais de 20 minutos para serem executadas atingem o tempo limite.
Quando a extensão terminar de ser processada, você poderá criar um Segment usando sua extensão de segmento e direcionar esse novo Segment com suas Campaigns e seus Canvas.
Etapa 2: Escreva seu SQL
Sua consulta de SQL deve ser escrita usando a sintaxe do Snowflake. Consulte a referência de tabelas para ver a lista completa de tabelas e colunas disponíveis para consulta.

As tabelas disponíveis para consulta contêm apenas dados de eventos. Se quiser consultar atributos de usuário, combine seu Segment SQL com filtros de atributos personalizados do segmentador clássico.
Além disso, seu SQL deve seguir estas regras:
- Escreva uma única instrução SQL. Não inclua ponto e vírgula.
- Seu SQL deve selecionar apenas uma coluna: a coluna
user_id. Isso significa que seu SQL deve conter:
SELECT DISTINCT user_id FROM "INSERT TABLE NAME"
- Não é possível consultar usuários com zero eventos. Portanto, qualquer consulta de usuários que realizaram um evento menos de X vezes precisa seguir esta alternativa:
- Escreva uma consulta para selecionar usuários que realizaram o evento MAIS de X vezes.
- Ao referenciar sua extensão de segmento no seu Segment, selecione
não incluipara inverter o resultado.
Requisitos da coluna user_id
A coluna user_id deve ser uma referência direta e inalterada ao user_id de uma tabela de origem. A Braze rejeita consultas em que a coluna user_id final é:
- Uma coluna calculada com um alias, como
COALESCE(m.orphaned_by_id, c.user_id) AS user_id - Outra coluna renomeada para
user_id, comom.orphaned_by_id AS user_id - Uma coluna de subconsulta com o alias
user_id, como ao selecionar de uma subconsulta que retorna umuser_idcalculado
Se você receber o erro “sql - Please select only the following columns: user_id”, mas sua consulta já seleciona a coluna user_id, verifique se ela usa algum desses padrões. A prévia pode funcionar mesmo que a consulta não seja salva.

Use GROUP BY c.user_id ou DISTINCT c.user_id diretamente da sua tabela de origem, em vez de usar um alias ou calcular a coluna user_id.
Regras adicionais
Além disso, sua consulta de SQL padrão deve seguir estas regras:
- Não é possível usar instruções
DECLARE.
Todas as consultas de atualização incremental têm duas partes: uma consulta e os detalhes do esquema.
- No editor, escreva uma consulta que selecione
user_ids da tabela desejada. - Adicione os detalhes do esquema selecionando um Operador, um Número de vezes e um Período nos campos na parte superior do editor. A consulta verifica se a soma da coluna agregada atende à condição definida nesses campos. Isso funciona de forma semelhante ao fluxo de criação de extensões de segmento clássicas.
- Operador: Indique se o evento aconteceu mais que, menos que ou exatamente um determinado número de vezes.

- Número de vezes: Quantas vezes você quer avaliar o evento em relação ao operador.

- Período: Número de dias, de 1 a 730, em que você quer verificar as ocorrências do evento. Esse período se refere aos dias anteriores em relação ao dia atual. O exemplo a seguir mostra uma consulta de usuários que realizaram o evento mais de 5 vezes nos últimos 365 dias.

- Operador: Indique se o evento aconteceu mais que, menos que ou exatamente um determinado número de vezes.
No exemplo a seguir, o Segment resultante conteria usuários que realizaram o evento favorited mais de 3 vezes nos últimos 30 dias, após uma data especificada.



A atualização incremental considera eventos atrasados, ou seja, eventos que chegam depois da janela de atualização diária, como eventos do SDK que não foram enviados no momento em que foram capturados. Quando o Segment é atualizado, a Braze reprocessa as datas a que esses eventos atrasados pertencem.
Como a atualização incremental acompanha os usuários ao longo do tempo
Quando você usa a atualização incremental, a Braze armazena contagens diárias de cada usuário em uma tabela interna de contagens. Assim, ela consegue avaliar seu Segment ao longo de todo o período sem consultar novamente todos os dados históricos a cada dia.
O que é armazenado: A Braze mantém uma tabela de contagens (semelhante a uma tabela de coortes de Segment) que acumula as contagens diárias de qualificação de usuários no formato (date, user_id, count). Essa tabela mantém os dados históricos fora da janela móvel de atualização de dois dias.
O que acontece em cada atualização: Quando uma atualização incremental é executada, a Braze limpa da tabela de contagens apenas os registros da janela móvel de atualização de dois dias. Em seguida, ela executa novamente sua consulta de SQL com parâmetros de tempo atualizados (usando $start_date) para inserir novas linhas para essas datas. As linhas históricas fora da janela móvel de atualização de dois dias permanecem intactas na tabela de contagens.
Como a Braze decide quem faz parte do Segment: A Braze avalia os critérios de associação ao seu Segment com base em toda a tabela de contagens acumulada, e não apenas na carga útil mais recente da janela móvel de atualização de dois dias. Isso significa que usuários que se qualificaram há mais de dois dias continuam no Segment, a menos que as contagens agregadas deixem de atender aos seus critérios.
Como escrever SQL que atualiza de forma confiável: Ao escrever SQL para atualização incremental, evite padrões de consulta que possam gerar resultados inconsistentes durante atualizações parciais. Por exemplo, agregações em janela como MAX(time), que dependem de dados além dos limites de $start_date, podem alterar o estado das linhas de forma inesperada quando apenas parte das datas é recalculada. Estruture suas consultas para que o resultado de cada data dependa apenas dos eventos daquela data. Assim, os resultados ficam consistentes, seja a consulta processando dois dias ou 730 dias de dados.
Regras adicionais
Além disso, sua consulta de atualização incremental deve seguir estas regras:
- Escreva uma única instrução SQL. Não inclua ponto e vírgula.
- Seu Segment SQL incremental pode fazer referência a apenas um evento. Os menus suspensos de data e contagem se aplicam a esse evento.
- Seu SQL deve incluir o alias
$date()(por exemplo,$date(time)), selecionaruser_ide uma agregaçãoCOUNT(), agrupar por data euser_ide filtrar com$start_datena sua coluna de tempo (por exemplo,time > $start_date). Salvar um SQL sem$date()ou sem esses campos retorna um erro. - Não é possível usar instruções
DECLARE.

Se você estiver criando um Segment SQL que usa a tabela CATALOGS_ITEMS_SHARED, é necessário especificar um ID de catálogo. Por exemplo:
SELECT * FROM CATALOGS_ITEMS_SHARED
WHERE CATALOG_ID = 'XYZ'
LIMIT 10
Etapa 3: Visualize a prévia da consulta
Antes de salvar, você pode executar uma prévia da sua consulta. As prévias de consulta são limitadas automaticamente a 100 linhas e atingem o tempo limite após 60 segundos. O requisito da coluna user_id não se aplica ao executar uma prévia.
Para extensões de segmento SQL incrementais, a prévia não inclui os critérios adicionais dos campos de operador, número de vezes e período.
Etapa 4: Determine se você precisa inverter o SQL
Em seguida, determine se você precisa inverter o SQL. Embora não seja possível consultar diretamente usuários com zero eventos, você pode usar Inverter SQL para direcionar esses usuários.

Por padrão, a opção Inverter SQL não está ativada. No entanto, se você usar o gerador de SQL com IA para gerar uma instrução SQL que precisa ser negada, o modelo pode retornar um resultado que ativa esse recurso automaticamente.
Por exemplo, para direcionar usuários com menos de três compras, primeiro escreva uma consulta que selecione usuários com três ou mais compras. Depois, selecione Inverter SQL para direcionar usuários com menos de três compras (incluindo aqueles com zero compras).

A menos que você queira direcionar especificamente usuários com zero eventos, não será necessário inverter o SQL. Se Inverter SQL estiver selecionado, confirme que o recurso é necessário e que o Segment corresponde ao público desejado. Por exemplo, se uma consulta direciona usuários com pelo menos um evento, ao ser invertida ela direcionará apenas usuários com zero eventos.

Atualizar a associação ao Segment
Para atualizar a associação ao Segment de qualquer extensão de segmento criada com SQL, abra a extensão de segmento e selecione Atualizar.

Se você criou um Segment em que espera que os usuários entrem e saiam com frequência, atualize manualmente a extensão de segmento usada por ele antes de direcionar esse Segment em uma Campaign ou Canvas.
Gerenciar suas extensões de segmento
Na página Extensões de segmento, os segmentos gerados com SQL aparecem com o ícone ao lado do nome.
Selecione uma extensão de segmento SQL para ver onde ela está sendo usada, arquivá-la ou atualizar manualmente a associação ao segmento.

Definir as configurações de atualização
Se não precisar que sua extensão seja atualizada regularmente, você pode salvá-la sem usar as configurações de atualização, e a Braze gerará sua extensão de Segment com base na associação do usuário naquele momento. Use o comportamento padrão se quiser gerar o público apenas uma vez e depois direcioná-lo com uma Campaign única.
Seu Segment sempre começará a ser processado após o salvamento inicial. Sempre que seu Segment for atualizado, a Braze executará novamente o Segment e atualizará a associação do Segment para refletir os usuários em seu Segment no momento da atualização. Isso pode ajudar suas Campaigns recorrentes a alcançar os usuários mais relevantes.
Configuração de uma atualização recorrente
Para definir uma programação recorrente designando configurações de atualização, selecione Ativar atualização. A opção de designar configurações de atualização está disponível para todos os tipos de extensões de Segment, incluindo segmentos SQL, extensões de Segment CDI e extensões de Segment simples baseadas em formulário.

Para otimizar seu gerenciamento de dados, as configurações de atualização são automaticamente desativadas para extensões de Segment não utilizadas. As extensões de Segment são consideradas não utilizadas quando:
- Não são usadas em nenhuma Campaign, Canvas ou Segment ativo ou inativo (rascunho, interrompido, arquivado); ou
- Não foram modificadas há mais de 7 dias
A Braze notificará o contato da empresa e o criador da extensão se essa configuração for desativada. A opção de regenerar extensões diariamente pode ser ativada novamente a qualquer momento.
Seleção das configurações de atualização

No painel Configurações de intervalo de atualização, você pode selecionar a frequência de atualização dessa extensão de Segment: por hora, diariamente, semanalmente ou mensalmente. Também será necessário selecionar o horário específico (no fuso horário da sua empresa) em que a atualização ocorrerá, como por exemplo:
- Se você tiver uma Campaign de e-mail que é enviada todas as segundas-feiras às 11h, horário da empresa, e quiser garantir que seu Segment seja atualizado logo antes do envio, escolha uma programação de atualização semanal às 10h das segundas-feiras.
- Se quiser que seu Segment seja atualizado todos os dias, selecione a frequência de atualização diária e, em seguida, escolha a hora do dia para atualizar.

A capacidade de definir uma programação de atualização por hora não está disponível para extensões de Segment baseadas em formulário (mas você pode definir programações diárias, semanais ou mensais).
Consumo de crédito e custos adicionais
Como as atualizações executam novamente a consulta do seu Segment, cada atualização para segmentos SQL consumirá créditos de Segment SQL, e cada atualização para extensões de Segment CDI incorrerá em um custo no seu data warehouse de terceiros.

Os segmentos podem levar até 60 minutos para serem atualizados devido ao tempo de processamento dos dados. Os segmentos que estão em processo de atualização terão o status “Processing” na lista de extensões de Segment. Isso tem algumas implicações:
- Para concluir o processamento do seu Segment antes de um horário específico, escolha um horário de atualização que seja 60 minutos antes.
- Somente uma atualização pode ocorrer de cada vez para uma extensão de Segment específica. Se houver um conflito em que uma nova atualização seja iniciada quando uma atualização existente já tiver começado a ser processada, a Braze cancelará a nova solicitação de atualização e continuará o processamento em andamento.
Critérios para desativar automaticamente extensões obsoletas
As atualizações programadas são automaticamente desativadas quando uma extensão de Segment se torna obsoleta. Uma extensão de Segment é considerada obsoleta se atender aos seguintes critérios:
- Não é usada em nenhuma Campaign ou Canvas ativo
- Não é usada em nenhum Segment que esteja em uma Campaign ou Canvas ativo
- Não é usada em nenhum Segment que tenha o rastreamento de análise de dados ativado
- Não foi modificada há mais de sete dias
- Não foi adicionada a uma Campaign ou Canvas (incluindo rascunhos) ou Segment há mais de sete dias
Se a atualização programada for desativada para uma extensão de Segment, essa extensão terá uma notificação informando isso.

Quando estiver pronto para usar uma extensão de Segment obsoleta, revise as configurações de atualização, selecione a programação de atualização que corresponda ao seu caso de uso e salve as modificações.
Créditos do Snowflake
Cada espaço de trabalho da Braze tem 5 créditos do Snowflake disponíveis por mês. Se precisar de mais créditos, entre em contato com o gerente da sua conta. Os créditos são usados sempre que você atualiza, ou salva e atualiza, a associação de um Segment SQL. Os créditos não são usados quando você executa prévias em um Segment SQL ou quando salva ou atualiza uma extensão de segmento clássica.

Os créditos do Snowflake não são compartilhados entre os recursos. Os créditos das extensões de segmento SQL são independentes dos créditos do Criador de consultas, que por padrão são 10 por empresa por mês.
O uso de créditos está relacionado ao tempo de execução da sua consulta de SQL. Quanto maior o tempo de execução, mais créditos a consulta vai custar. O tempo de execução pode variar de acordo com a complexidade e o tamanho das suas consultas ao longo do tempo. Quanto mais consultas complexas e frequentes você executar, maior será a alocação de recursos e mais rápido será o tempo de execução.
Para economizar créditos, faça uma prévia da sua consulta para garantir que ela esteja correta antes de salvar a extensão de segmento SQL.
Seus créditos voltam para 5 no primeiro dia de cada mês, à meia-noite (0h) UTC. Você pode monitorar o uso dos seus créditos durante o mês no painel de uso de créditos. Na página Extensões de segmento, clique em Ver uso de créditos SQL.

Quando seus créditos chegarem a zero, acontecerá o seguinte:
- Todas as extensões de segmento SQL configuradas para atualização automática deixam de ser atualizadas. Isso afeta a associação desses segmentos e todas as Campaigns ou Canvas direcionados a eles.
- Você só poderá salvar novas extensões de segmento SQL como rascunhos durante o restante do mês.
Todos os usuários da empresa que criaram um Segment SQL e os administradores da sua empresa vão receber um e-mail de notificação quando você tiver usado 50%, 80% e 100% dos seus créditos. Depois que seus créditos forem redefinidos no início do mês seguinte, você poderá criar mais Segments SQL, e as atualizações automáticas serão retomadas.
Se quiser comprar mais créditos de Segment SQL ou extensões de segmento adicionais, entre em contato com o gerente da sua conta.