Extensions de segments SQL

Vous pouvez générer une extension de segment à l’aide de requêtes SQL Snowflake sur des données Snowflake. Le SQL vous aide à exploiter de nouveaux cas d’usage de segments, car il offre la flexibilité nécessaire pour décrire les relations entre les données d’une manière qui n’est pas réalisable avec les autres fonctionnalités de segmentation.

Comme les extensions de segments standard, vous pouvez interroger les événements des deux dernières années (730 jours) dans votre extension de segment SQL. Contrairement aux extensions de segments standard, les extensions de segments SQL consomment des crédits.

Prérequis

Pour utiliser les extensions de segments SQL, vous avez besoin des autorisations suivantes pour votre espace de travail :

Créer une extension de segment

Étape 1 : Choisir un éditeur

Vous avez le choix entre deux types d’éditeurs SQL pour créer votre extension de segment SQL : l’éditeur SQL et l’éditeur SQL incrémentiel.

• Actualisation complète : À chaque actualisation de votre segment, Braze interroge toutes les données disponibles pour le mettre à jour. Cette méthode consomme plus de crédits que l’actualisation incrémentielle. Les extensions à actualisation complète peuvent régénérer automatiquement leur appartenance chaque jour, mais elles ne peuvent pas utiliser l’actualisation incrémentielle.
• Actualisation incrémentielle : L’actualisation incrémentielle est une façon plus économique de configurer votre requête, même si sa configuration demande quelques étapes supplémentaires. Si vous pouvez effectuer ces étapes en construisant votre segment, cette option vaut le coup, car votre requête consommera moins de crédits.
• Générateur SQL IA : Le générateur SQL IA vous permet de rédiger une instruction en langage courant, qu’il transforme en requête SQL pour votre segment. C’est un moyen rapide de démarrer sans avoir à écrire le SQL vous-même.

Conseil

Vous pouvez effectuer une actualisation complète manuelle sur tous les segments SQL créés dans l’un ou l’autre des éditeurs SQL.

• actualisation complète
• actualisation incrémentielle
• générateur sql ia

Pour créer une extension de segment SQL à actualisation complète :

1. Allez dans Audience > Extensions de segments.
2. Sélectionnez Créer une nouvelle extension, puis Actualisation complète.
   
   
   
   
3. Donnez un nom à votre extension de segment et saisissez votre SQL. Consultez l’étape 2 pour connaître les exigences et les ressources disponibles.
   
   
   
   
4. Enregistrez votre extension de segment.

Pour créer une extension de segment SQL à actualisation incrémentielle :

1. Allez dans Audience > Extensions de segments.
2. Sélectionnez Créer une nouvelle extension, puis Actualisation incrémentielle.
   
   
   
   
3. Donnez un nom à votre extension de segment et saisissez votre SQL. Consultez la section Écrire du SQL pour connaître les exigences et les ressources disponibles.
   
   
   
   
4. Si vous le souhaitez, sélectionnez Régénérer l’extension quotidiennement.
   
   
   
   Lorsque cette option est sélectionnée, Braze met automatiquement à jour l’appartenance au segment chaque jour. Concrètement, chaque jour à minuit dans le fuseau horaire de votre entreprise (avec un éventuel retard d’une heure), Braze recherche les nouveaux utilisateurs de votre segment et les y ajoute automatiquement. Si une extension de segment n’a pas été utilisée depuis 7 jours, Braze suspend automatiquement la régénération quotidienne. Une extension de segment inutilisée est une extension qui ne fait partie d’aucune Campaign ni d’aucun Canvas (la Campaign ou le Canvas n’a pas besoin d’être actif pour que l’extension soit considérée comme « utilisée »).
   
   
5. Enregistrez votre extension de segment.

Remarque

Le générateur SQL IA est actuellement disponible en version bêta. Contactez votre gestionnaire de la satisfaction client si vous souhaitez participer à cet essai bêta.

Le générateur SQL IA s’appuie sur GPT, fourni par OpenAI, pour recommander du SQL pour votre segment SQL.

Pour utiliser le générateur SQL IA, procédez comme suit :

1. Sélectionnez Lancer le générateur SQL IA après avoir créé un segment SQL avec une actualisation complète ou incrémentielle.
2. Saisissez votre instruction et sélectionnez Générer pour la traduire en SQL.
3. Vérifiez que le SQL généré semble correct, puis enregistrez votre segment.

Exemples d’instructions

• Utilisateurs ayant reçu un e-mail au cours du dernier mois
• Utilisateurs ayant effectué moins de cinq achats au cours de l’année écoulée

Conseils

• Familiarisez-vous avec les tables de données Snowflake disponibles. 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 propres à cette fonctionnalité. Le non-respect de ces règles provoque une erreur. Par exemple, votre code SQL doit sélectionner la colonne user_id. Commencer votre instruction par « utilisateurs qui » peut vous aider.
• Vous pouvez envoyer jusqu’à 20 instructions par minute avec le générateur SQL 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.

Remarque

Les requêtes SQL dont l’exécution dure plus de 20 minutes expirent.

Une fois le traitement de l’extension terminé, vous pouvez créer un segment à partir de votre extension de segment et cibler ce nouveau segment avec vos Campaigns et vos Canvas.

Étape 2 : Écrire votre SQL

Votre requête SQL doit être rédigée selon la syntaxe Snowflake. Consultez la référence des tables pour obtenir la liste complète des tables et colonnes que vous pouvez interroger.

Important

Notez que les tables disponibles pour vos requêtes contiennent uniquement des données d’événements. Si vous souhaitez interroger des attributs utilisateur, combinez votre segment SQL avec des filtres d’attributs personnalisés du segmenteur classique.

• sql editor
• incremental sql editor

Votre SQL doit également respecter les règles suivantes :

• Rédigez une seule instruction SQL. N’incluez aucun point-virgule.
• Votre SQL doit sélectionner une seule colonne : la colonne user_id. Votre SQL doit donc contenir :

1

SELECT DISTINCT user_id FROM "INSERT TABLE NAME"

• Il n’est pas possible d’interroger les utilisateurs n’ayant aucun événement. Toute requête portant sur des utilisateurs ayant réalisé un événement moins de X fois doit donc suivre cette solution de contournement :
  1. Rédigez une requête qui sélectionne les utilisateurs ayant réalisé l’événement PLUS de X fois.
  2. Lorsque vous référencez votre extension de segment dans votre segment, sélectionnez n’inclut pas pour inverser le résultat.

Exigences relatives à la colonne user_id

La colonne user_id doit être une référence directe et non modifiée à la colonne user_id d’une table source. Braze rejette les requêtes dans lesquelles la colonne user_id finale est :

• Une colonne calculée avec un alias, par exemple COALESCE(m.orphaned_by_id, c.user_id) AS user_id
• Une autre colonne renommée en user_id, par exemple m.orphaned_by_id AS user_id
• Une colonne de sous-requête avec l’alias user_id, par exemple une sélection à partir d’une sous-requête qui renvoie une colonne user_id calculée

Si vous recevez l’erreur « sql - Please select only the following columns: user_id » alors que votre requête sélectionne déjà la colonne user_id, vérifiez si elle utilise l’un de ces modèles. L’aperçu peut fonctionner même si l’enregistrement de la requête échoue.

Conseil

Utilisez GROUP BY c.user_id ou DISTINCT c.user_id directement depuis votre table source au lieu d’attribuer un alias à la colonne user_id ou de la calculer.

Règles supplémentaires

Votre requête SQL standard doit également respecter les règles suivantes :

• Vous ne pouvez pas utiliser d’instructions DECLARE.

Toutes les requêtes à actualisation incrémentielle se composent de deux parties : une requête et des détails de schéma.

1. Dans l’éditeur, rédigez une requête qui sélectionne des user_id dans la table de votre choix.
2. Ajoutez les détails de schéma en sélectionnant un Opérateur, un Nombre de fois et une Période dans les champs situés en haut de l’éditeur. La requête vérifie si la somme de la colonne agrégée remplit la condition définie dans ces champs. Ce fonctionnement est similaire au processus de création des extensions de segments classiques.
   
   
   • Opérateur : Indiquez si l’événement s’est produit plus de, moins de ou exactement un certain nombre de fois.
     
     
     
   • Nombre de fois : Le nombre de fois que vous souhaitez évaluer l’événement par rapport à l’opérateur.
     
     
     
   • Période : Le nombre de jours, de 1 à 730, sur lequel vous souhaitez vérifier les occurrences de l’événement. Cette période correspond aux jours passés par rapport au jour actuel. L’exemple suivant interroge les utilisateurs ayant réalisé l’événement plus de 5 fois au cours des 365 derniers jours.
     

Dans l’exemple suivant, le segment obtenu contiendrait les utilisateurs ayant réalisé l’événement favorited plus de 3 fois au cours des 30 derniers jours, après une date donnée.

Conseil

L’actualisation incrémentielle tient compte des événements tardifs, c’est-à-dire des événements qui arrivent après la fenêtre d’actualisation quotidienne, comme les événements SDK qui n’ont pas été envoyés au moment de leur capture. Lorsque le segment est actualisé, Braze retraite les dates auxquelles appartiennent ces événements tardifs.

Comment l’actualisation incrémentielle suit les utilisateurs dans le temps

Avec l’actualisation incrémentielle, Braze stocke des comptages quotidiens pour chaque utilisateur dans une table de comptage interne. Cela lui permet d’évaluer votre segment sur toute la période choisie sans réinterroger chaque jour l’ensemble des données historiques.

Ce qui est stocké : Braze gère une table de comptage (semblable à une table de cohortes de segment) qui cumule les comptages quotidiens de qualification des utilisateurs au format (date, user_id, count). Cette table conserve les données historiques en dehors de la fenêtre d’actualisation glissante de deux jours.

Ce qui se passe à chaque actualisation : Lors d’une actualisation incrémentielle, Braze efface uniquement les enregistrements de la fenêtre d’actualisation glissante de deux jours dans la table de comptage. Il réexécute ensuite votre requête SQL avec des paramètres temporels mis à jour (à l’aide de $start_date) pour insérer de nouvelles lignes pour ces dates. Les lignes historiques situées en dehors de cette fenêtre de deux jours restent intactes dans la table de comptage.

Comment Braze détermine qui fait partie du segment : Braze évalue vos critères d’appartenance au segment par rapport à l’ensemble de la table de comptage cumulée, et pas seulement par rapport aux données de la dernière actualisation glissante de deux jours. Les utilisateurs qui se sont qualifiés il y a plus de deux jours restent donc dans le segment, sauf si leurs comptages agrégés ne remplissent plus vos critères.

Écrire un SQL qui s’actualise de façon fiable : Lorsque vous rédigez du SQL pour l’actualisation incrémentielle, évitez les modèles de requête susceptibles de produire des résultats incohérents lors d’actualisations partielles. Par exemple, des agrégations fenêtrées comme MAX(time) qui dépendent de données de part et d’autre des limites de $start_date peuvent modifier l’état des lignes de façon inattendue lorsque seule une partie des dates est recalculée. Structurez vos requêtes de sorte que le résultat de chaque date dépende uniquement des événements de cette date : vous obtiendrez ainsi des résultats cohérents, que la requête traite deux jours ou 730 jours de données.

Règles supplémentaires

Votre requête à actualisation incrémentielle doit également respecter les règles suivantes :

• Rédigez une seule instruction SQL. N’incluez aucun point-virgule.
• Votre segment SQL incrémentiel ne peut faire référence qu’à un seul événement. Les menus déroulants de date et de comptage s’appliquent à cet événement.
• Votre SQL doit inclure l’alias $date() (par exemple, $date(time)), sélectionner user_id et une agrégation COUNT(), regrouper par date et par user_id, et filtrer avec $start_date sur votre colonne temporelle (par exemple, time > $start_date). L’enregistrement d’un SQL sans $date() ou sans ces champs renvoie une erreur.
• Vous ne pouvez pas utiliser d’instructions DECLARE.

Remarque

Si vous créez un segment SQL qui utilise la table CATALOGS_ITEMS_SHARED, vous devez spécifier un ID de catalogue. Par exemple :

1
2
3

SELECT * FROM CATALOGS_ITEMS_SHARED
WHERE CATALOG_ID = 'XYZ'
LIMIT 10

Étape 3 : Prévisualiser la requête

Avant d’enregistrer, vous pouvez lancer un aperçu de votre requête. Les aperçus de requête sont automatiquement limités à 100 lignes et expirent au bout de 60 secondes. L’exigence relative à la colonne user_id ne s’applique pas lors d’un aperçu.

Pour les extensions de segments SQL incrémentielles, l’aperçu n’inclut pas les critères supplémentaires définis dans les champs Opérateur, Nombre de fois et Période.

Étape 4 : Déterminer si vous devez inverser le SQL

Déterminez ensuite si vous devez inverser le SQL. S’il n’est pas possible d’interroger directement les utilisateurs n’ayant aucun événement, vous pouvez utiliser Inverser le SQL pour cibler ces utilisateurs.

Remarque

Par défaut, l’option Inverser le SQL n’est pas activée. Toutefois, si vous utilisez le générateur SQL IA pour générer une instruction SQL qui doit être inversée, ChatGPT peut renvoyer un résultat qui active automatiquement cette fonctionnalité.

Par exemple, pour cibler les utilisateurs ayant effectué moins de trois achats, rédigez d’abord une requête qui sélectionne les utilisateurs ayant effectué trois achats ou plus. Sélectionnez ensuite Inverser le SQL pour cibler les utilisateurs ayant effectué moins de trois achats (y compris ceux qui n’en ont effectué aucun).

Important

Sauf si vous cherchez spécifiquement à cibler des utilisateurs n’ayant aucun événement, vous n’aurez pas besoin d’inverser le SQL. Si Inverser le SQL est sélectionné, vérifiez que cette fonctionnalité est nécessaire et que le segment correspond bien à l’audience souhaitée. Par exemple, si une requête cible les utilisateurs ayant au moins un événement, une fois inversée, elle ciblera uniquement les utilisateurs n’ayant aucun événement.

Actualisation de l’appartenance au segment

Pour actualiser l’appartenance au segment de toute extension de segment créée à l’aide de SQL, ouvrez l’extension de segment et sélectionnez Actualiser.

Conseil

Si vous avez créé un segment dans lequel vous vous attendez à ce que les utilisateurs entrent et sortent régulièrement, actualisez manuellement l’extension de segment qu’il utilise avant de cibler ce segment dans une campagne ou un Canvas.

Gestion de vos extensions de segments

Sur la page Extensions de segments, les Segments générés avec SQL sont signalés par l’icône à côté de leur nom.

Sélectionnez une extension de segment SQL pour voir où elle est utilisée, l’archiver ou actualiser manuellement l’appartenance au Segment.

Définir les paramètres d’actualisation

Si vous n’avez pas besoin que votre extension soit actualisée à intervalles réguliers, vous pouvez l’enregistrer sans utiliser les paramètres d’actualisation, et Braze générera par défaut votre extension de segments en fonction de l’appartenance des utilisateurs à ce moment-là. Utilisez le comportement par défaut si vous souhaitez générer l’audience une seule fois, puis la cibler avec une campagne ponctuelle.

Votre segment commencera toujours à être traité après l’enregistrement initial. À chaque actualisation de votre segment, Braze réexécute le segment et met à jour l’appartenance au segment pour refléter les utilisateurs présents dans votre segment au moment de l’actualisation. Cela peut aider vos campagnes récurrentes à atteindre les utilisateurs les plus pertinents.

Mise en place d’une actualisation récurrente

Pour établir une planification récurrente en définissant des paramètres d’actualisation, sélectionnez Activer l’actualisation. L’option de définition des paramètres d’actualisation est disponible pour tous les types d’extensions de segments, y compris les segments SQL, les extensions de segments CDI et les extensions de segments basées sur des formulaires simples.

Important

Pour optimiser la gestion de vos données, les paramètres d’actualisation sont automatiquement désactivés pour les extensions de segments non utilisées. Les extensions de segments sont considérées comme non utilisées lorsqu’elles :

• Ne sont utilisées dans aucune campagne, aucun Canvas ni aucun segment actif ou inactif (brouillon, arrêté, archivé) ; ou
• N’ont pas été modifiées depuis plus de 7 jours

Braze informera le contact de la société et le créateur de l’extension si ce paramètre est désactivé. L’option de régénération quotidienne des extensions peut être réactivée à tout moment.

Sélectionner vos paramètres d’actualisation

Dans le panneau Paramètres d’intervalle d’actualisation, vous pouvez sélectionner la fréquence à laquelle cette extension de segments sera actualisée : toutes les heures, tous les jours, toutes les semaines ou tous les mois. Vous devrez également sélectionner l’heure précise (dans le fuseau horaire de votre société) à laquelle l’actualisation doit avoir lieu, par exemple :

• Si vous avez une campagne d’e-mail envoyée tous les lundis à 11 h, heure de la société, et que vous souhaitez vous assurer que votre segment est actualisé juste avant l’envoi, vous devriez choisir une planification d’actualisation hebdomadaire à 10 h les lundis.
• Si vous souhaitez que votre segment soit actualisé tous les jours, sélectionnez la fréquence d’actualisation quotidienne, puis choisissez l’heure de l’actualisation.

Remarque

La possibilité de définir une planification d’actualisation horaire n’est pas disponible pour les extensions de segments basées sur des formulaires (mais vous pouvez définir des planifications quotidiennes, hebdomadaires ou mensuelles).

Consommation de crédits et coûts supplémentaires

Étant donné que les actualisations réexécutent la requête de votre segment, chaque actualisation pour les segments SQL consommera des crédits de segment SQL, et chaque actualisation pour les extensions de segments CDI entraînera un coût au sein de votre entrepôt de données third-party.

Remarque

L’actualisation des segments peut prendre jusqu’à 60 minutes en raison des temps de traitement des données. Les segments en cours d’actualisation auront un statut « En cours de traitement » dans votre liste d’extensions de segments. Cela a plusieurs implications :

• Pour terminer le traitement de votre segment avant une heure précise, choisissez une heure d’actualisation située 60 minutes plus tôt.
• Il ne peut y avoir qu’une seule actualisation à la fois pour une extension de segments donnée. En cas de conflit où une nouvelle actualisation est lancée alors qu’une actualisation existante a déjà commencé à être traitée, Braze annulera la nouvelle demande d’actualisation et poursuivra le traitement en cours.

Critères de désactivation automatique des extensions périmées

Les actualisations planifiées sont automatiquement désactivées lorsqu’une extension de segments est périmée. Une extension de segments est périmée si elle répond aux critères suivants :

• Non utilisée dans des campagnes ou des Canvas actifs
• Non utilisée dans un segment faisant partie d’une campagne ou d’un Canvas actif
• Non utilisée dans un segment où le suivi analytique est activé
• Non modifiée depuis plus de sept jours
• Non ajoutée à une campagne, un Canvas (y compris les brouillons) ou un segment depuis plus de sept jours

Si l’actualisation planifiée est désactivée pour une extension de segments, une notification l’indique pour cette extension.

Lorsque vous êtes prêt à utiliser une extension de segments périmée, passez en revue les paramètres d’actualisation, sélectionnez la planification d’actualisation qui correspond à votre cas d’usage, puis enregistrez les modifications.

Crédits Snowflake

Chaque espace de travail Braze dispose de 5 crédits Snowflake par mois. Si vous avez besoin de crédits supplémentaires, contactez votre gestionnaire de compte. Les crédits sont consommés chaque fois que vous actualisez, ou enregistrez et actualisez, l’appartenance d’un segment SQL. Les crédits ne sont pas utilisés lorsque vous exécutez des aperçus dans un segment SQL ou lorsque vous enregistrez ou actualisez une extension de segment classique.

Remarque

Les crédits Snowflake ne sont pas partagés entre les fonctionnalités. Par exemple, les crédits des extensions de segments SQL et du générateur de requêtes sont indépendants les uns des autres.

La consommation de crédits est corrélée à la durée d’exécution de votre requête SQL. Plus la durée d’exécution est longue, plus la requête coûtera de crédits. La durée d’exécution peut varier en fonction de la complexité et de la taille de vos requêtes au fil du temps. Plus vous exécutez des requêtes complexes et fréquentes, plus votre allocation de ressources est importante et plus votre temps d’exécution diminue.

Pour économiser des crédits, prévisualisez votre requête pour vous assurer qu’elle est correcte avant d’enregistrer l’extension de segment SQL.

Vos crédits sont réinitialisés à 5 le premier de chaque mois à 00h00 UTC. Vous pouvez suivre votre consommation de crédits tout au long du mois dans le panneau d’utilisation des crédits. Depuis la page Segment Extensions, cliquez sur View SQL Credit Usage.

Voici ce qui se passe lorsque vos crédits atteignent zéro :

• Toutes les extensions de segments SQL configurées pour s’actualiser automatiquement cessent de s’actualiser, ce qui impacte l’appartenance à ces segments ainsi que toutes les Campaigns ou Canvas qui ciblent ces segments.
• Vous ne pouvez enregistrer les nouvelles extensions de segments SQL qu’en tant que brouillons pour le reste du mois.

Tous les utilisateurs de l’entreprise ayant créé un segment SQL ainsi que les administrateurs de votre entreprise recevront un e-mail de notification lorsque vous aurez utilisé 50 %, 80 % et 100 % de vos crédits. Après la réinitialisation de vos crédits au début du mois suivant, vous pourrez créer de nouveaux segments SQL et les actualisations automatiques reprendront.

Si vous souhaitez acheter des crédits de segments SQL supplémentaires ou des extensions de segments supplémentaires, contactez votre gestionnaire de compte.