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éation d’une extension de segment

Étape 1 : Choisissez un éditeur

Deux types d’éditeurs SQL s’offrent à vous 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, ce qui consomme plus de crédits qu’une actualisation incrémentielle. Les extensions à actualisation complète peuvent régénérer automatiquement leur appartenance chaque jour, mais ne peuvent pas être actualisées de manière incrémentielle.
• Actualisation incrémentielle : L’actualisation incrémentielle est un moyen plus économique de configurer votre requête, même si sa configuration demande quelques étapes supplémentaires. Si vous pouvez effectuer ces étapes lors de la création de votre segment, cette option vaut la peine, car votre requête consomme moins de crédits.
• Générateur SQL IA : Le générateur SQL IA vous permet de rédiger une invite en langage courant et la 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 de 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

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 campagnes et vos Canvas.

Étape 2 : Rédigez votre SQL

Votre requête SQL doit utiliser 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 les requêtes ne contiennent que des données d’événements. Si vous souhaitez interroger des attributs utilisateur, combinez votre segment SQL avec des filtres d’attributs personnalisés issus du segmenteur classique.

• éditeur sql
• éditeur sql incrémentiel

Votre SQL doit en outre 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 visant les utilisateurs ayant effectué 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 effectué 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 depuis une sous-requête qui renvoie un user_id calculé

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. La prévisualisation 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.

Toute requête à actualisation incrémentielle comporte 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 souhaitée.
2. Ajoutez les détails du schéma en sélectionnant un Opérateur, un Nombre de fois et une Période dans les champs 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 semblable au flux de création des extensions de segments classiques.
   
   
   • Opérateur : Indiquez si l’événement s’est produit plus de fois, moins de fois ou exactement un certain nombre de fois.
     
     
     
   • Nombre de fois : Nombre d’occurrences de l’événement à évaluer par rapport à l’opérateur.
     
     
     
   • Période : 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 effectué l’événement plus de 5 fois au cours des 365 derniers jours.
     

Dans l’exemple suivant, le segment obtenu contiendrait les utilisateurs ayant effectué l’événement favorited plus de 3 fois au cours des 30 derniers jours, après une date spécifié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. Lors de l’actualisation du segment, Braze retraite les dates auxquelles ces événements tardifs appartiennent.

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

Avec l’actualisation incrémentielle, Braze stocke des décomptes quotidiens pour chaque utilisateur dans une table de décomptes interne. Il peut ainsi évaluer votre segment sur toute la période définie sans réinterroger chaque jour l’ensemble des données historiques.

Ce qui est stocké : Braze gère une table de décomptes (semblable à une table de cohortes de segments) qui cumule les décomptes 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 supprime de la table de décomptes uniquement les enregistrements compris dans la fenêtre d’actualisation glissante de deux jours. 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 restent intactes dans la table de décomptes.

Comment Braze détermine qui fait partie du segment : Braze évalue vos critères d’appartenance au segment sur l’ensemble de la table de décomptes cumulée, et pas seulement sur le payload de la dernière actualisation glissante de deux jours. Ainsi, les utilisateurs qualifiés il y a plus de deux jours restent dans le segment, sauf si les décomptes agrégés ne remplissent plus vos critères.

Rédiger un SQL qui s’actualise de manière 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, les 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 seul un sous-ensemble de dates est recalculé. Structurez vos requêtes de sorte que le résultat de chaque date dépende uniquement des événements de cette date : vous obtiendrez 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. Vos listes déroulantes de date et de décompte 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évisualisez la requête

Avant d’enregistrer, vous pouvez lancer une prévisualisation de votre requête. Les prévisualisations sont automatiquement limitées à 100 lignes et expirent au bout de 60 secondes. L’exigence relative à la colonne user_id ne s’applique pas lors d’une prévisualisation.

Pour les extensions de segments SQL incrémentielles, la prévisualisation n’inclut pas les critères supplémentaires définis dans les champs d’opérateur, de nombre de fois et de période.

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

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

Remarque

Par défaut, Inverser SQL n’est pas activé. 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 SQL pour cibler les utilisateurs ayant effectué moins de trois achats (y compris ceux qui n’en ont effectué aucun).

Important

À moins que vous ne cherchiez spécifiquement à cibler des utilisateurs n’ayant aucun événement, vous n’aurez pas besoin d’inverser le SQL. Si Inverser 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.

Actualiser l’appartenance au segment

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

Conseil

Si vous avez créé un segment dans lequel les utilisateurs sont censés entrer et sortir 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 à l’aide de 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.