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.

Como o Criador de consultas permite acesso direto a alguns dados de cliente, você só pode acessá-lo se tiver a permissão “View PII”.

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 uma lista completa das tabelas disponíveis e suas colunas, consulte a referência de tabelas SQL.

Executando relatórios no Criador de consultas

Para executar um relatório no Criador de consultas:

1. Acesse Analytics > Query Builder.
2. Selecione Create SQL Query. Se precisar de inspiração ou ajuda para elaborar 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 hora atuais. Passe o cursor sobre o nome e selecione para dar um nome significativo à sua consulta SQL.
4. Escreva sua consulta SQL no editor ou obtenha ajuda da IA na guia AI Query Builder. Se estiver escrevendo seu próprio SQL, consulte Escrevendo consultas SQL personalizadas para requisitos e recursos.
5. Selecione Run Query.
6. Salve sua consulta.
7. Para baixar um CSV do seu relatório, selecione Export.

Os resultados de cada relatório podem ser gerados uma vez por dia. Se você executar o mesmo relatório mais de uma vez em um dia, verá os mesmos resultados em ambos os relatórios.

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 uma lista de modelos disponíveis.

Período dos dados

As consultas retornam dados dos últimos 60 dias. Se você usa Currents ou Compartilhamento de dados do Snowflake, pode ser possível consultar até dois anos de dados, que é o tempo de retenção dos seus dados no Snowflake. Para mais detalhes sobre 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. Portanto, pode haver algumas discrepâncias de dados entre sua 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:

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 no Criador de consultas exibe suas consultas executadas anteriormente para ajudar você a rastrear e reutilizar seu trabalho. O histórico de consultas é retido por sete dias, o que significa que 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 resultados de consultas importantes antes que expirem.

Gerando SQL com o AI Query Builder

O AI Query Builder utiliza o GPT, desenvolvido pela OpenAI, para recomendar SQL para sua consulta.

Para gerar SQL com o AI Query Builder:

1. Após 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 verificar se está correto e, em seguida, selecione Insert into Editor.

Dicas

• Familiarize-se com as tabelas e colunas disponíveis na referência de tabelas SQL. Solicitar dados que não existem nessas tabelas pode fazer com que o ChatGPT invente uma tabela fictícia.
• Familiarize-se com as regras de escrita SQL para este recurso. Não seguir essas regras causará um erro.
• Você pode enviar até 20 prompts por minuto com o AI Query Builder.

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 Query Builder, 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 .

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 utilizar tipos de variáveis predefinidos em SQL para referenciar valores sem precisar copiar o valor 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 diretamente uma Campaign em um menu suspenso na guia Variables.

Após uma variável ser criada, ela aparecerá na guia Variables do seu relatório no Criador de consultas. Os benefícios de usar variáveis SQL incluem:

• Economizar tempo criando uma variável de Campaign para selecionar de uma lista ao criar seu relatório, em vez de colar IDs de Campaign.
• Trocar valores adicionando variáveis que permitem reutilizar o relatório para casos de uso ligeiramente diferentes no futuro (como um evento personalizado diferente).
• Reduzir 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.

Diretrizes

As variáveis devem seguir a seguinte sintaxe Liquid: {{ type.${name}}}, onde type deve ser um dos tipos aceitos e name pode ser qualquer coisa 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 a menos que os valores das variáveis sejam selecionados), exceto o intervalo de datas, que assume como padrão os últimos 30 dias quando o valor não é fornecido.

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 fornecido, como 5.5
• Exemplo de uso: some_number_column < {{number.${some name}}}

Intervalo de datas

Se usar tanto start_date quanto end_date, eles devem ter o mesmo nome para que você possa usá-los 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.

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

• Valor de substituição: Substitui start_date e end_date por um timestamp Unix em segundos para uma data especificada em UTC, como 1696517353.
• Exemplo de uso: Para todas as variáveis de 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 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 seus estados em um grupo.

Canvas

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

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

Canvas (múltiplos)

Para selecionar múltiplos Canvas. Compartilhar o mesmo nome com uma Campaign resultará em um botão de opção na guia Variables para selecionar Canvas ou Campaign.

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

Campaign

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

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

Campaigns (múltiplas)

Para selecionar múltiplas Campaigns. Compartilhar o mesmo nome com um Canvas resultará em um botão de opção na guia Variables para selecionar Canvas ou Campaign.

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

Variantes de Campaign

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

• Valor de substituição: IDs de API das variantes de Campaign, strings delimitadas 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 usado com uma variável de Canvas ou Canvas (múltiplos).

• Valor de substituição: IDs de API das variantes de Canvas, strings delimitadas 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 usado 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 a Canvas escolhidos. Deve ser usado com uma variável de Canvas ou Canvas (múltiplos).

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