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 das seguintes 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 somente 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 obter 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 escrever 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 peça ajuda à IA na guia AI Query Builder. Se for escrever seu próprio SQL, consulte Escrevendo consultas SQL personalizadas para ver 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 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.

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 consultas no nosso banco de dados 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 sua consulta, adicione o seguinte SQL à consulta e personalize-o para 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. 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 de consultas 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 deduplicaçã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. A 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 nas diferentes fontes de relatórios, consulte Soft bounce no glossário de análise de dados de e-mail.

Gerar SQL com o Criador de consultas com IA

O Criador de consultas com IA usa o GPT, da OpenAI, para recomendar SQL para sua consulta.

Para gerar SQL com o Criador de consultas com IA:

1. Depois de criar um relatório no Criador de consultas, selecione a guia AI Query Builder.
2. Digite seu prompt ou selecione um prompt de exemplo e selecione Generate para traduzir seu prompt em SQL.
3. Revise o SQL gerado para confirmar que está correto e, em seguida, selecione Insert into Editor.

Dicas

• Conheça as tabelas e colunas disponíveis na referência de tabelas SQL. Se você pedir dados que não existem nessas tabelas, o ChatGPT pode inventar uma tabela falsa.
• Conheça as regras de escrita de SQL deste recurso. Se você não seguir essas regras, ocorrerá um erro.
• Você pode enviar até 20 prompts por minuto com o Criador de consultas com IA.

Como meus dados são usados e enviados para a OpenAI?

Para gerar saída de IA por meio dos recursos do BrazeAI que utilizam a OpenAI (“Saída”), a Braze enviará determinadas informações (“Entrada”) para a OpenAI. A Entrada consiste nos seus prompts e pode incluir o conteúdo exibido no dashboard e outros dados do espaço de trabalho relevantes para suas consultas, conforme aplicável. De acordo com os compromissos da plataforma de API da OpenAI, os dados enviados à API da OpenAI via Braze não são usados para treinar ou aprimorar os modelos da OpenAI. A OpenAI pode reter os dados por 30 dias para fins de monitoramento de abuso, após o que são excluídos. Entre você e a Braze, a Saída é sua propriedade intelectual. A Braze não fará nenhuma reivindicação de propriedade de direitos autorais sobre tal Saída. A Braze não oferece nenhuma garantia de qualquer tipo com relação a qualquer conteúdo gerado por IA, incluindo a Saída.

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 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. Os rótulos dessas variáveis usam o nome da variável por 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. Quando nenhum valor é informado, ele usa os últimos 30 dias por padrão.

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 juntos, 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. Se compartilhar o mesmo nome com uma Campaign, será exibido 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. Se compartilhar o mesmo nome com uma Campaign, será exibido 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. Se compartilhar o mesmo nome com um Canvas, será exibido 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. Se compartilhar o mesmo nome com um Canvas, será exibido 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 junto 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 de vários Canvas.

• 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 de vários Canvas.

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