Générateur de requêtes

Le Générateur de requêtes génère des rapports à partir des données de Braze dans Snowflake. Il est fourni avec des modèles de requêtes SQL prédéfinis pour vous aider à démarrer, ou vous pouvez écrire vos propres requêtes SQL personnalisées pour obtenir encore plus d’informations.

Conditions préalables

Pour utiliser le Générateur de requêtes, vous devez disposer des autorisations suivantes au niveau de l’espace de travail :

Tables de données disponibles

Le Générateur de requêtes utilise les mêmes tables SQL Snowflake que les extensions de segments SQL et le partage de données Snowflake. Pour obtenir la liste complète des tables disponibles et de leurs colonnes, consultez la référence des tables SQL.

Vues des attributs du profil utilisateur

Le Générateur de requêtes et les extensions de segments SQL incluent la plupart des vues des attributs du profil utilisateur, comme les instantanés périodiques et l’historique des attributs par défaut.

Deux vues d’attributs personnalisés sont disponibles uniquement via le partage de données Snowflake :

• USER_CUSTOM_ATTRIBUTES_HISTORY_VIEW_SHARED
• USER_LATEST_STATE_CUSTOM_ATTRIBUTE_VIEW_SHARED

Braze exclut ces vues du Générateur de requêtes et des extensions de segments SQL, car leur interrogation est lente à l’échelle d’un espace de travail et dépasse souvent le délai d’expiration. Utilisez USER_CUSTOM_ATTRIBUTES_VIEW_SHARED pour obtenir des instantanés d’attributs personnalisés dans le Générateur de requêtes. Si vous avez besoin de données d’attributs personnalisés historiques ou quasiment en temps réel, interrogez plutôt les vues exclues via le partage de données Snowflake.

Exécuter des rapports dans le Générateur de requêtes

Pour exécuter un rapport du Générateur de requêtes :

1. Accédez à Analyse > Générateur de requêtes.
2. Sélectionnez Créer une requête SQL. Si vous avez besoin d’inspiration ou d’aide pour rédiger votre requête, sélectionnez Modèle de requête et choisissez un modèle dans la liste. Sinon, sélectionnez Éditeur SQL pour accéder directement à l’éditeur.
3. Votre rapport reçoit automatiquement un nom comprenant la date et l’heure actuelles. Survolez le nom et sélectionnez pour donner un nom explicite à votre requête SQL.
4. Rédigez votre requête SQL dans l’éditeur ou faites-vous aider par l’IA depuis l’onglet Générateur de requêtes IA. Si vous écrivez votre propre requête SQL, consultez la section Rédiger des requêtes SQL personnalisées pour connaître les exigences et les ressources disponibles.
5. Sélectionnez Exécuter la requête.
6. Enregistrez votre requête.
7. Pour télécharger un fichier CSV de votre rapport, sélectionnez Exporter.

Chaque fois que vous exécutez un rapport, le Générateur de requêtes interroge les données actuellement disponibles dans Snowflake. Les résultats peuvent varier d’une exécution à l’autre, y compris au cours d’une même journée, à mesure que de nouvelles données arrivent. Les événements récents peuvent mettre un certain temps à apparaître en raison des délais d’ingestion et de traitement.

Modèles de requêtes

Accédez aux modèles de requêtes en sélectionnant Créer une requête SQL > Modèle de requête lors de la création d’un rapport.

Consultez Modèles de requêtes pour obtenir la liste des modèles disponibles.

Période des données

Les requêtes renvoient les données des 60 derniers jours. Si vous utilisez Currents ou le partage de données Snowflake, vous pourrez peut-être interroger jusqu’à deux ans de données, ce qui correspond à la durée de conservation de vos données dans Snowflake. Pour en savoir plus sur la conservation prolongée des données, contactez votre Customer Success Manager.

Fuseau horaire du Générateur de requêtes

Le fuseau horaire par défaut pour interroger notre base de données Snowflake est UTC. Par conséquent, il peut y avoir des écarts de données entre votre page Engagement du canal e-mail (qui suit le fuseau horaire de votre entreprise) et les résultats de votre Générateur de requêtes.

Pour convertir le fuseau horaire dans les résultats de votre requête, ajoutez le code SQL suivant à votre requête et adaptez-le au fuseau horaire de votre entreprise :

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;

Historique des requêtes

La section Historique des requêtes du Générateur de requêtes affiche les requêtes que vous avez déjà exécutées, pour vous aider à suivre et réutiliser votre travail. L’historique des requêtes est conservé pendant sept jours : les requêtes de plus de sept jours sont automatiquement supprimées.

Si vous devez auditer l’utilisation des requêtes sur des périodes plus longues ou conserver des enregistrements au-delà de sept jours, nous vous recommandons d’exporter ou d’enregistrer les résultats de requêtes importants avant leur expiration.

Comparer le Générateur de requêtes avec d’autres sources de rapports

Les résultats du Générateur de requêtes peuvent différer de ceux d’autres outils de reporting, car ils s’appuient sur des sources de données et des méthodes de traitement différentes.

Par exemple, le nombre d’échecs provisoires d’envoi dans le Générateur de requêtes peut être plus élevé que dans les rapports SendGrid Deliverability. Le Générateur de requêtes comptabilise toutes les occurrences d’échecs provisoires d’envoi, sans déduplication. Si un utilisateur subit plusieurs échecs provisoires d’envoi avant la réception finale (ou après des tentatives prolongées), chaque tentative en échec provisoire est comptabilisée. SendGrid Deliverability utilise ses propres données et sa propre logique, auxquelles Braze n’a pas accès : les chiffres des deux rapports peuvent donc ne pas correspondre.

Pour en savoir plus sur le suivi des échecs provisoires d’envoi dans les différentes sources de rapports, consultez la section Échec provisoire d’envoi du glossaire d’analyse des e-mails.

Générer du SQL avec le Générateur de requêtes IA

Le Générateur de requêtes IA s’appuie sur GPT, fourni par OpenAI, pour vous suggérer du SQL adapté à votre requête.

Pour générer du SQL avec le Générateur de requêtes IA :

1. Après avoir créé un rapport dans le Générateur de requêtes, sélectionnez l’onglet Générateur de requêtes IA.
2. Saisissez votre invite ou sélectionnez un exemple d’invite, puis sélectionnez Générer pour convertir votre invite en SQL.
3. Vérifiez que le SQL généré vous semble correct, puis sélectionnez Insérer dans l’éditeur.

Conseils

• Familiarisez-vous avec les tables et colonnes disponibles dans la référence des tables SQL. Si vous demandez des données qui n’existent pas dans ces tables, ChatGPT risque d’inventer une table fictive.
• Familiarisez-vous avec les règles d’écriture SQL de cette fonctionnalité. Le non-respect de ces règles entraînera une erreur.
• Vous pouvez envoyer jusqu’à 20 invites par minute avec le Générateur de requêtes IA.

Comment mes données sont-elles utilisées et envoyées à OpenAI ?

Pour générer une sortie d’intelligence artificielle via les fonctionnalités BrazeAI qui exploitent OpenAI (« Sortie »), Braze enverra certaines informations (« Entrée ») à OpenAI. L’Entrée se compose de vos invites et peut inclure le contenu affiché dans le tableau de bord, ainsi que d’autres données de l’espace de travail pertinentes pour vos requêtes, le cas échéant. Conformément aux engagements de la plateforme API d’OpenAI, les données envoyées à l’API d’OpenAI via Braze ne sont pas utilisées pour entraîner ou améliorer les modèles d’OpenAI. OpenAI peut conserver les données pendant 30 jours à des fins de surveillance des abus, après quoi elles sont supprimées. Entre vous et Braze, la Sortie est votre propriété intellectuelle. Braze ne revendiquera aucun droit d’auteur sur cette Sortie. Braze n’offre aucune garantie de quelque nature que ce soit concernant tout contenu généré par l’intelligence artificielle, y compris la Sortie.

Écrire des requêtes SQL personnalisées

Écrivez votre requête SQL en utilisant la syntaxe Snowflake. Consultez la référence des tables pour une liste complète des tables et colonnes disponibles pour les requêtes.

Pour afficher les détails des tables dans le Générateur de requêtes :

1. Depuis la page Query Builder, ouvrez le panneau Reference et sélectionnez Available Data Tables pour afficher les tables de données disponibles et leurs noms.
2. Sélectionnez See Details pour afficher la description de la table et les informations sur les colonnes, telles que les types de données.
3. Pour insérer le nom de la table dans votre SQL, sélectionnez Copy table name to SQL editor.

Pour utiliser des requêtes pré-écrites fournies par Braze, sélectionnez Query Template lors de la création initiale d’un rapport dans le Générateur de requêtes.

Restreindre votre requête à une période spécifique vous aidera à générer des résultats plus rapidement. Voici un exemple de requête qui obtient le nombre d’achats et le chiffre d’affaires généré au cours de la dernière heure.

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()));

Cette requête récupère le nombre d’envois d’e-mails au cours du dernier mois :

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()));

Si vous interrogez CANVAS_ID, CANVAS_VARIATION_API_ID ou CAMPAIGN_ID, les colonnes de noms associées seront automatiquement incluses dans le tableau de résultats. Vous n’avez pas besoin de les inclure dans la requête SELECT elle-même.

Cette requête récupère les trois ID et leurs colonnes de noms associées avec un maximum de 100 lignes :

1
2
3

SELECT CANVAS_ID, CANVAS_VARIATION_API_ID, CAMPAIGN_ID
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
LIMIT 100

Remplir automatiquement le nom de la variante de campagne

Si vous souhaitez que le nom de la variante de campagne soit automatiquement rempli, incluez le nom de colonne MESSAGE_VARIATION_API_ID dans votre requête, comme dans cet exemple :

1
2
3

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

Résolution des problèmes

Votre requête peut échouer pour l’une des raisons suivantes :

• Erreurs de syntaxe dans votre requête SQL
• Délai de traitement dépassé (après 6 minutes)
  • Les rapports dont l’exécution prend plus de 6 minutes expireront.
  • Si un rapport expire, essayez de limiter la période sur laquelle vous interrogez les données ou d’interroger un ensemble de données plus spécifique.

Utiliser des variables

Les variables vous permettent d’utiliser des types de variables prédéfinis en SQL pour référencer des valeurs sans avoir à les copier manuellement. Par exemple, au lieu de copier manuellement l’ID d’une Campaign dans l’éditeur SQL, vous pouvez utiliser {{campaign.${My campaign}}} pour sélectionner directement une Campaign dans une liste déroulante de l’onglet Variables.

Une fois créée, une variable apparaît dans l’onglet Variables de votre rapport du Générateur de requêtes. Les avantages de l’utilisation de variables SQL incluent :

• Gagnez du temps en créant une variable de Campaign pour sélectionner dans une liste lors de la création de votre rapport, au lieu de coller des ID de Campaign.
• Remplacez des valeurs en ajoutant des variables qui vous permettent de réutiliser le rapport pour des cas d’usage légèrement différents à l’avenir (comme un événement personnalisé différent).
• Réduisez les erreurs utilisateur lors de la modification de votre SQL en limitant la quantité de modifications nécessaires pour chaque rapport. Les collègues plus à l’aise avec SQL peuvent créer des rapports que des collègues moins techniques peuvent ensuite utiliser.

Lignes directrices

Les variables doivent respecter la syntaxe Liquid suivante : {{ type.${name}}}, où type doit correspondre à l’un des types acceptés et name peut être la valeur de votre choix. Par défaut, le libellé de ces variables correspond au nom de la variable.

Par défaut, toutes les variables sont obligatoires (votre rapport ne s’exécutera pas tant que leurs valeurs ne sont pas sélectionnées), à l’exception de la plage de dates, qui correspond par défaut aux 30 derniers jours lorsqu’aucune valeur n’est fournie.

Types de variables

Les types de variables suivants sont acceptés :

• Nombre
• Plage de dates
• Messagerie
• Produits
• Événements personnalisés
• Propriétés des événements personnalisés
• Espace de travail
• Catalogues
• Champs de catalogue
• Options
• Segments
• Chaîne de caractères
• Tags

Nombre

• Valeur de remplacement : La valeur fournie, par exemple 5.5
• Exemple d’utilisation : some_number_column < {{number.${some name}}}

Plage de dates

Si vous utilisez à la fois start_date et end_date, ils doivent porter le même nom pour pouvoir être utilisés comme plage de dates.

Exemples de valeurs

Le type de plage de dates peut être relatif, une date de début, une date de fin ou une plage de dates.

Les quatre types s’affichent si start_date et end_date sont tous deux utilisés avec le même nom. Si un seul est utilisé, seuls les types pertinents s’affichent.

• Valeur de remplacement : Remplace start_date et end_date par un horodatage Unix en secondes correspondant à une date donnée en UTC, par exemple 1696517353.
• Exemple d’utilisation : Pour toutes les variables de type relatif, date de début, date de fin et plage de dates :
  • time > {{start_date.${some name}}} AND time < {{end_date.${some name}}}
    • Vous pouvez utiliser uniquement start_date ou end_date si vous ne souhaitez pas de plage de dates.

Messagerie

Toutes les variables de messagerie doivent partager le même identifiant lorsque vous souhaitez lier leur état au sein d’un même groupe.

Canvas

Permet de sélectionner un seul Canvas. Partager le même nom avec une Campaign affiche, dans l’onglet Variables, un bouton radio permettant de choisir entre Canvas et Campaign.

• Valeur de remplacement : ID BSON du Canvas
• Exemple d’utilisation : canvas_id = ‘{{canvas.${some name}}}’

Canvas (plusieurs)

Permet de sélectionner plusieurs Canvas. Partager le même nom avec une Campaign affiche, dans l’onglet Variables, un bouton radio permettant de choisir entre Canvas et Campaign.

• Valeur de remplacement : ID BSON des Canvas
• Exemple d’utilisation : canvas_id IN ({{canvases.${some name}}})

Campaign

Permet de sélectionner une seule Campaign. Partager le même nom avec un Canvas affiche, dans l’onglet Variables, un bouton radio permettant de choisir entre Canvas et Campaign.

• Valeur de remplacement : ID BSON de la Campaign
• Exemple d’utilisation : campaign_id = ‘{{campaign.${some name}}}’

Campaigns

Permet de sélectionner plusieurs Campaigns. Partager le même nom avec un Canvas affiche, dans l’onglet Variables, un bouton radio permettant de choisir entre Canvas et Campaign.

• Valeur de remplacement : ID BSON des Campaigns
• Exemple d’utilisation : campaign_id IN ({{campaigns.${some name}}})

Variantes de campagne

Permet de sélectionner les variantes de campagne appartenant à la Campaign sélectionnée. Doit être utilisée conjointement avec une variable de Campaign ou de Campaigns.

• Valeur de remplacement : ID d’API des variantes de campagne, sous forme de chaînes séparées par des virgules, par exemple api-id1, api-id2.
• Exemple d’utilisation : message_variation_api_id IN ({{campaign_variants.${some name}}})

Variantes du canvas

Permet de sélectionner les variantes du canvas appartenant à un Canvas choisi. Doit être utilisée avec une variable de Canvas ou de Canvas multiples.

• Valeur de remplacement : ID d’API des variantes du canvas, sous forme de chaînes séparées par des virgules, par exemple api-id1, api-id2.
• Exemple d’utilisation : canvas_variation_api_id IN ({{canvas_variants.${some name}}})

Étape du canvas

Permet de sélectionner une étape du canvas appartenant à un Canvas choisi. Doit être utilisée avec une variable de Canvas.

• Valeur de remplacement : ID d’API de l’étape du canvas
• Exemple d’utilisation : canvas_step_api_id = ‘{{canvas_step.${some name}}}’

Étapes du canvas

Permet de sélectionner des étapes du canvas appartenant aux Canvas choisis. Doit être utilisée avec une variable de Canvas ou de Canvas multiples.

• Valeur de remplacement : ID d’API des étapes du canvas
• Exemple d’utilisation : canvas_step_api_id IN ({{canvas_steps.${some name}}})