Criador de consultas

O Criador de consultas gera relatórios usando dados da Braze no Snowflake. O Criador de consultas vem com modelos de consulta SQL pré-criados para você começar, ou você pode escrever suas próprias consultas SQL personalizadas para obter ainda mais insights.

Pré-requisitos

Para usar o Criador de consultas, você precisa destas permissões no nível do espaço de trabalho:

Tabelas de dados disponíveis

O Criador de consultas usa as mesmas tabelas SQL do Snowflake que as extensões de segmento SQL e o Compartilhamento de dados do Snowflake. Para ver a lista completa de tabelas disponíveis e suas colunas, consulte a referência de tabelas SQL.

Visualizações de atributos do perfil de usuário

O Criador de consultas e as extensões de segmento SQL incluem a maioria das visualizações de atributos do perfil de usuário, como snapshots periódicos e o histórico de atributos padrão.

Duas visualizações de atributos personalizados estão disponíveis apenas pelo Compartilhamento de dados do Snowflake:

• USER_CUSTOM_ATTRIBUTES_HISTORY_VIEW_SHARED
• USER_LATEST_STATE_CUSTOM_ATTRIBUTE_VIEW_SHARED

A Braze exclui essas visualizações do Criador de consultas e das extensões de segmento SQL porque as consultas nelas são lentas na escala de um espaço de trabalho e costumam atingir o tempo limite. No Criador de consultas, use USER_CUSTOM_ATTRIBUTES_VIEW_SHARED para snapshots de atributos personalizados. Se você precisar de dados históricos ou quase em tempo real de atributos personalizados, consulte as visualizações excluídas pelo Compartilhamento de dados do Snowflake.

Executar relatórios no Criador de consultas

Para executar um relatório do Criador de consultas:

1. Acesse Analytics > Query Builder.
2. Selecione Create SQL Query. Se você precisar de inspiração ou ajuda para montar sua consulta, selecione Query Template e escolha um modelo da lista. Caso contrário, selecione SQL Editor para ir direto ao editor.
3. Seu relatório recebe automaticamente um nome com a data e a hora atuais. Passe o mouse sobre o nome e selecione para dar à sua consulta SQL um nome mais significativo.
4. Escreva sua consulta SQL no editor ou selecione Ask Operator para gerar SQL com o Operator. Se for escrever seu próprio SQL, consulte Escrever consultas SQL personalizadas para ver os requisitos e recursos.
5. Selecione Run Query.
6. Salve sua consulta.
7. Para baixar um CSV do seu relatório, selecione Export.

Sempre que você executa um relatório, o Criador de consultas consulta os dados disponíveis no momento no Snowflake. Os resultados podem mudar entre uma execução e outra, inclusive no mesmo dia, à medida que novos dados chegam. Eventos recentes podem demorar a aparecer devido a atrasos de ingestão e processamento.

Modelos de consulta

Acesse os modelos de consulta selecionando Create SQL Query > Query Template ao criar um relatório pela primeira vez.

Consulte Modelos de consulta para ver a lista de modelos disponíveis.

Período dos dados

As consultas retornam dados dos últimos 60 dias. Se você usa o Currents ou o Snowflake Data Sharing, talvez consiga consultar até dois anos de dados, que é o período em que seus dados ficam retidos no Snowflake. Para saber mais sobre a retenção estendida de dados, entre em contato com seu gerente de sucesso do cliente.

Fuso horário do Criador de consultas

O fuso horário padrão para consultar nosso banco de dados no Snowflake é UTC. Por isso, pode haver algumas discrepâncias de dados entre a página Email Channel Engagement (que segue o fuso horário da sua empresa) e os resultados do Criador de consultas.

Para converter o fuso horário nos resultados da consulta, adicione o SQL a seguir à sua consulta e personalize-o com o fuso horário da sua empresa:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

SELECT
DATE_TRUNC(
'day',
CONVERT_TIMEZONE('UTC','Australia/Sydney', TO_TIMESTAMP(TIME))
) AS send_date_sydney,
COUNT(ID) AS emails_sent
USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE
-- Apply the date range in Sydney time as well
CONVERT_TIMEZONE('UTC','Australia/Sydney', TO_TIMESTAMP(TIME)) >= '2025-03-25 00:00:00'
AND CONVERT_TIMEZONE('UTC','Australia/Sydney', TO_TIMESTAMP(TIME)) < '2025-03-29 00:00:00'
AND APP_GROUP_ID = 'your app group ID'
GROUP BY
send_date_sydney
ORDER BY
send_date_sydney;

Histórico de consultas

A seção Query history do Criador de consultas mostra as consultas que você já executou, para ajudar você a acompanhar e reutilizar seu trabalho. O histórico de consultas fica disponível por sete dias. Então, consultas com mais de sete dias são removidas automaticamente.

Se você precisar auditar o uso de consultas por períodos mais longos ou manter registros além de sete dias, recomendamos exportar ou salvar os resultados importantes antes que expirem.

Comparar o Criador de consultas com outras fontes de relatórios

Os resultados do Criador de consultas podem ser diferentes dos de outras ferramentas de relatório, porque elas usam fontes de dados e métodos de processamento diferentes.

Por exemplo, a contagem de soft bounces no Criador de consultas pode ser maior do que nos relatórios de entregabilidade do SendGrid. O Criador de consultas conta todas as ocorrências de soft bounce, sem desduplicação. Se um usuário tiver vários soft bounces antes da entrega final (ou depois de novas tentativas prolongadas), cada tentativa com soft bounce é contada. O SendGrid Deliverability usa dados e lógica próprios, aos quais a Braze não tem acesso. Portanto, as contagens dos dois relatórios podem não coincidir.

Para saber mais sobre como os soft bounces são rastreados em diferentes fontes de relatório, consulte Soft bounce no Glossário de análise de dados de e-mail.

Gerar SQL com o Operator

Nota

Esse recurso agora faz parte do BrazeAI Operator™, o assistente de IA unificado da Braze. Os recursos de IA que antes estavam disponíveis como assistentes independentes agora podem ser acessados pelo Operator de qualquer lugar em que você já esteja trabalhando no dashboard.

No painel lateral do Criador de consultas, selecione Ask Operator e descreva os dados que você quer. O Operator escreve SQL com base nas tabelas de dados da Braze disponíveis. Você pode revisar o SQL e ver uma prévia dos resultados antes de executar seu relatório. Para usar o Operator no Criador de consultas, você precisa da permissão “Edit Dashboard Reports”.

O SQL gerado precisa seguir as mesmas regras de escrita de SQL das consultas que você mesmo escreve. Para saber mais, consulte O que você pode fazer com o Operator. Para entender como o Operator lida com seus dados, consulte Privacidade e segurança de dados do Operator.

Escrevendo consultas SQL personalizadas

Escreva sua consulta SQL usando a sintaxe do Snowflake. Consulte a referência de tabelas para uma lista completa de tabelas e colunas disponíveis para consulta.

Para visualizar detalhes das tabelas dentro do Criador de consultas:

1. Na página do Criador de consultas, abra o painel Reference e selecione Available Data Tables para visualizar as tabelas de dados disponíveis e seus nomes.
2. Selecione See Details para visualizar a descrição da tabela e informações sobre as colunas, como tipos de dados.
3. Para inserir o nome da tabela no seu SQL, selecione Copy table name to SQL editor.

Para usar consultas pré-escritas fornecidas pela Braze, selecione Query Template ao criar um relatório pela primeira vez no Criador de consultas.

Restringir sua consulta a um período específico ajudará a gerar resultados mais rapidamente. A seguir, um exemplo de consulta que obtém o número de compras e a receita gerada na última hora.

1
2
3

SELECT COUNT(*) as Purchases, SUM(price) as Revenue
FROM USERS_BEHAVIORS_PURCHASE_SHARED
WHERE to_date(to_timestamp_ntz(time)) >= DATEADD('hour', -1, date_trunc('day',CURRENT_DATE()));

Esta consulta recupera o número de envios de e-mail no último mês:

1
2
3

SELECT COUNT(*) as Sends
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE to_date(to_timestamp_ntz(time)) >= DATEADD('month', -1, date_trunc('day',CURRENT_DATE()));

Se você consultar CANVAS_ID, CANVAS_VARIATION_API_ID ou CAMPAIGN_ID, as colunas de nome associadas serão automaticamente incluídas na tabela de resultados. Você não precisa incluí-las na própria consulta SELECT.

Esta consulta recupera todos os três IDs e suas colunas de nome associadas com um máximo de 100 linhas:

1
2
3

SELECT CANVAS_ID, CANVAS_VARIATION_API_ID, CAMPAIGN_ID
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
LIMIT 100

Preencher automaticamente o nome da variante de campanha

Se você quiser que o nome da variante de campanha seja preenchido automaticamente, inclua o nome da coluna MESSAGE_VARIATION_API_ID na sua consulta, como neste exemplo:

1
2
3

SELECT CANVAS_ID, CANVAS_VARIATION_API_ID, CAMPAIGN_ID, MESSAGE_VARIATION_API_ID
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
LIMIT 100

Solução de problemas

Sua consulta pode falhar por qualquer um dos seguintes motivos:

• Erros de sintaxe na sua consulta SQL
• Tempo limite de processamento (após 6 minutos)
  • Relatórios que levam mais de 6 minutos para serem executados atingirão o tempo limite.
  • Se um relatório atingir o tempo limite, tente limitar o período no qual você está consultando dados ou consulte um conjunto de dados mais específico.

Usando variáveis

Use variáveis para aplicar tipos de variáveis predefinidos no SQL e referenciar valores sem precisar copiá-los manualmente. Por exemplo, em vez de copiar manualmente o ID de uma Campaign para o editor SQL, você pode usar {{campaign.${My campaign}}} para selecionar uma Campaign diretamente em um menu suspenso na guia Variables.

Depois de criada, a variável aparece na guia Variables do seu relatório do Criador de consultas. Os benefícios de usar variáveis SQL incluem:

• Economize tempo criando uma variável de campanha para selecionar a partir de uma lista ao criar seu relatório, em vez de colar IDs de Campaign.
• Substitua valores adicionando variáveis que permitem reutilizar o relatório para casos de uso ligeiramente diferentes no futuro (como um evento personalizado diferente).
• Reduza erros do usuário ao editar seu SQL, diminuindo a quantidade de edição necessária para cada relatório. Colegas mais familiarizados com SQL podem criar relatórios que colegas menos técnicos podem usar em seguida.

Diretrizes

As variáveis devem seguir esta sintaxe Liquid: {{ type.${name}}}, onde type deve ser um dos tipos aceitos e name pode ser qualquer nome que você escolher. Os rótulos dessas variáveis usam o nome da variável como padrão.

Por padrão, todas as variáveis são obrigatórias (e seu relatório não será executado se os valores das variáveis não forem selecionados), exceto o intervalo de datas, que usa os últimos 30 dias como padrão quando nenhum valor é informado.

Tipos de variáveis

Os seguintes tipos de variáveis são aceitos:

• Número
• Intervalo de datas
• Envio de mensagens
• Produtos
• Eventos personalizados
• Propriedades de eventos personalizados
• Espaço de trabalho
• Catálogos
• Campos de catálogo
• Opções
• Segments
• String
• Tags

Número

• Valor de substituição: O valor informado, como 5.5
• Exemplo de uso: some_number_column < {{number.${some name}}}

Intervalo de datas

Se você usar start_date e end_date, eles devem ter o mesmo nome para que possam ser usados como um intervalo de datas.

Valores de exemplo

O tipo de intervalo de datas pode ser relativo, data de início, data de término ou intervalo de datas.

Os quatro tipos são exibidos se start_date e end_date forem usados com o mesmo nome. Se apenas um deles for usado, somente os tipos relevantes serão exibidos.

• Valor de substituição: Substitui start_date e end_date por um carimbo de data/hora Unix em segundos para uma data especificada em UTC, como 1696517353.
• Exemplo de uso: Para todas as variáveis de tipo relativo, data de início, data de término e intervalo de datas:
  • time > {{start_date.${some name}}} AND time < {{end_date.${some name}}}
    • Você pode usar apenas start_date ou end_date se não quiser um intervalo de datas.

Envio de mensagens

Todas as variáveis de envio de mensagens devem compartilhar o mesmo identificador quando você quiser vincular o estado delas em um único grupo.

Canvas

Para selecionar um Canvas. Compartilhar o mesmo nome com uma Campaign resulta em um botão de opção na guia Variables para selecionar Canvas ou Campaign.

• Valor de substituição: ID BSON do Canvas
• Exemplo de uso: canvas_id = ‘{{canvas.${some name}}}’

Canvas (vários)

Para selecionar vários Canvas. Compartilhar o mesmo nome com uma Campaign resulta em um botão de opção na guia Variables para selecionar Canvas ou Campaign.

• Valor de substituição: IDs BSON dos Canvas
• Exemplo de uso: canvas_id IN ({{canvases.${some name}}})

Campaign

Para selecionar uma Campaign. Compartilhar o mesmo nome com um Canvas resulta em um botão de opção na guia Variables para selecionar Canvas ou Campaign.

• Valor de substituição: ID BSON da Campaign
• Exemplo de uso: campaign_id = ‘{{campaign.${some name}}}’

Campaigns

Para selecionar várias Campaigns. Compartilhar o mesmo nome com um Canvas resulta em um botão de opção na guia Variables para selecionar Canvas ou Campaign.

• Valor de substituição: IDs BSON das Campaigns
• Exemplo de uso: campaign_id IN ({{campaigns.${some name}}})

Variantes de campanha

Para selecionar variantes de campanha que pertencem à Campaign selecionada. Deve ser usada em conjunto com uma variável de Campaign ou Campaigns.

• Valor de substituição: IDs de API das variantes de campanha, strings separadas por vírgulas, como api-id1, api-id2.
• Exemplo de uso: message_variation_api_id IN ({{campaign_variants.${some name}}})

Variantes do Canvas

Para selecionar variantes do Canvas que pertencem a um Canvas escolhido. Deve ser usada com uma variável de Canvas ou Canvas (vários).

• Valor de substituição: IDs de API das variantes do Canvas, strings separadas por vírgulas, como em api-id1, api-id2.
• Exemplo de uso: canvas_variation_api_id IN ({{canvas_variants.${some name}}})

Etapa do Canvas

Para selecionar uma etapa do Canvas que pertence a um Canvas escolhido. Deve ser usada com uma variável de Canvas.

• Valor de substituição: ID de API da etapa do Canvas
• Exemplo de uso: canvas_step_api_id = ‘{{canvas_step.${some name}}}’

Etapas do Canvas

Para selecionar etapas do Canvas que pertencem aos Canvas escolhidos. Deve ser usada com uma variável de Canvas ou Canvas (vários).

• Valor de substituição: IDs de API das etapas do Canvas
• Exemplo de uso: canvas_step_api_id IN ({{canvas_steps.${some name}}})