Ir para o conteúdo

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:

Permissão O que permite
“View Dashboard Reports” Abrir o Criador de consultas no dashboard
“View PII” Acessar os dados do Criador de consultas, que podem incluir dados de cliente
“Edit Dashboard Reports” Criar, editar e executar relatórios do Criador de consultas

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 elas são lentas para consultar 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.

Executando 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 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 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 Escrevendo consultas SQL personalizadas para ver os requisitos e recursos.
  5. Use o filtro de intervalo de datas para definir a janela de tempo dos seus resultados. Você pode escolher um intervalo fixo ou uma janela relativa. Consulte Período dos dados para saber até quando no passado você pode selecionar.
  6. Selecione Run Query. O dashboard mostra até as primeiras 1.000 linhas.
  7. Salve sua consulta.
  8. Para baixar um CSV do seu relatório, selecione Export. As exportações podem incluir até 100.000 linhas.

Criador de consultas mostrando os resultados da consulta de modelo "Engajamento e receita por canal nos últimos 30 dias".

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 execuções, 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

Use o filtro de intervalo de datas em um relatório para escolher quais dias de dados incluir. Você pode selecionar no máximo um ano de histórico, a menos que seu espaço de trabalho tenha o Snowflake Data Sharing ou o Currents, que permitem selecionar até dois anos de dados. Para saber mais sobre a retenção estendida de dados, entre em contato com seu gerente de sucesso do cliente.

Resultados e exportações

O dashboard mostra até as primeiras 1.000 linhas de resultados. Ao exportar, o CSV pode incluir até 100.000 linhas. Para relatórios que precisam de mais dados do que isso, use o Currents ou os endpoints de exportação da API.

Créditos de SQL

Cada empresa tem 10 créditos do Snowflake disponíveis por mês para o Criador de consultas, compartilhados entre todos os espaços de trabalho. Para saber como os créditos são consumidos, redefinidos e ampliados, consulte Créditos do Snowflake.

Fuso horário do Criador de consultas

O fuso horário padrão para consultar nosso banco de dados Snowflake é o 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 sua consulta, adicione o seguinte SQL à sua consulta e personalize-o para o fuso horário da sua empresa:

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 exibe as consultas que você executou anteriormente para ajudar você a acompanhar e reutilizar seu trabalho. O histórico de consultas fica disponível por sete dias. Ou seja, 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 por mais de sete dias, recomendamos exportar ou salvar os resultados importantes antes que expirem.

Comparando 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 após novas tentativas prolongadas), cada tentativa com soft bounce é contada. O relatório de entregabilidade do SendGrid 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órios, consulte Soft bounce no glossário de análise de dados de e-mail.

Gerando SQL com o Operator

No painel lateral do Criador de consultas, selecione Ask Operator e descreva os dados que você deseja. O Operator escreve SQL com base nas tabelas de dados da Braze disponíveis, e 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 deve seguir as mesmas regras de escrita de SQL que as 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.

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:

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.

Nome do ID Coluna de nome associada
CANVAS_ID Canvas Name
CANVAS_VARIATION_API_ID Canvas Variant Name
CAMPAIGN_ID Campaign Name

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

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:

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 que uma variável é criada, ela 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}}}, em que type deve ser um dos tipos aceitos e name pode ser qualquer nome que você escolher. Por padrão, os rótulos dessas variáveis usam o nome da variável.

Por padrão, todas as variáveis são obrigatórias, e seu relatório não será executado enquanto os valores das variáveis não forem selecionados. A exceção é o intervalo de datas: quando nenhum valor é informado, ele usa por padrão os últimos 30 dias.

Tipos de variáveis

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

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 juntos, eles devem ter o mesmo nome para que possam funcionar 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 aparecem quando start_date e end_date são usados com o mesmo nome. Se apenas um deles for usado, só os tipos relevantes serão exibidos.

Tipo de intervalo de datas Descrição Valores necessários
Relativo Especifica os últimos X dias Requer start_date
Data de início Especifica uma data de início Requer start_date
Data de término Especifica uma data de término Requer end_date
Intervalo de datas Especifica uma data de início e uma data de término Requer start_date e end_date
  • Valor de substituição: Substitui start_date e end_date por um carimbo de data/hora Unix em segundos para a 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 apenas 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. Se você usar o mesmo nome de uma Campaign, um botão de opção aparecerá na guia Variables para selecionar Canvas ou Campaign.

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

Para selecionar vários Canvas. Se você usar o mesmo nome de uma Campaign, um botão de opção aparecerá 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. Se você usar o mesmo nome de um Canvas, um botão de opção aparecerá 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. Se você usar o mesmo nome de um Canvas, um botão de opção aparecerá 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 de Canvas

Para selecionar variantes de Canvas que pertencem a um Canvas escolhido. Deve ser usada com uma variável de Canvas ou Canvases.

  • Valor de substituição: IDs de API das variantes de 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 Canvases.

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