Ingestion de données cloud : éditeur SQL
Cette page explique comment utiliser l’éditeur SQL de l’ingestion de données cloud (CDI) de Braze pour créer et valider des synchronisations avec des requêtes SQL.
L’éditeur SQL de l’ingestion de données cloud vous permet de créer des synchronisations en écrivant des requêtes SQL directement sur votre entrepôt de données. Cela supprime la nécessité de créer ou de maintenir une table CDI dédiée, ce qui était auparavant requis dans l’étape 1.1 des intégrations d’entrepôt de données.
Utilisez l’éditeur SQL lorsque vous souhaitez :
- Synchroniser des données sans modifier les tables en amont
- Travailler avec des données brutes dans votre entrepôt
- Éviter de construire une colonne
PAYLOAD - Gérer des cas d’utilisation de données plus complexes avec SQL
L’éditeur SQL de l’ingestion de données cloud est en bêta. Contactez votre gestionnaire de la satisfaction client ou votre gestionnaire de compte pour y accéder.
Conditions préalables et limitations
L’éditeur SQL présente les limitations suivantes :
- Disponible uniquement pour les sources d’entrepôt de données : Snowflake, Redshift, BigQuery, Databricks et Fabric.
- Seules les requêtes en lecture seule à instruction unique sont prises en charge.
Braze exécute uniquement des requêtes en lecture seule sur vos données et ne modifie pas vos tables sous-jacentes. Des objets temporaires peuvent être créés pendant l’exécution des requêtes, mais ne sont pas conservés.
Créer une nouvelle synchronisation avec l’éditeur SQL
Suivez ces étapes pour créer d’abord une source, puis une synchronisation avec l’éditeur SQL. Si vous avez déjà configuré une source pour CDI, vous pouvez passer à l’étape 3.
Notez que ces étapes utilisent une source Snowflake comme exemple. Le processus de configuration pour les autres sources d’entrepôt de données est similaire et peut être consulté dans l’étape 2 : Créer une nouvelle source dans le tableau de bord de Braze de la documentation Configuration des intégrations d’entrepôt de données.
Étape 1 : Configurer votre rôle, vos autorisations, votre entrepôt et votre utilisateur Snowflake
Avant de créer votre source Snowflake dans CDI, assurez-vous que l’utilisateur Snowflake utilisé par Braze a accès aux données que vous souhaitez interroger et à un entrepôt pour exécuter les requêtes.
Étape 1.1 : (Facultatif) Créer une base de données et un schéma
Si nécessaire, créez une base de données et un schéma dédiés pour vos données CDI :
1
2
CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
Étape 1.2 : Configurer le rôle et les autorisations de base de données
Accordez l’accès aux tables que vous souhaitez synchroniser :
1
2
3
4
5
CREATE ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.MY_USER_TABLE TO ROLE BRAZE_INGESTION_ROLE;
Vous pouvez également accorder l’accès à plusieurs tables ou à des tables futures, selon votre cas d’utilisation. Par exemple, pour accorder l’accès à toutes les futures tables d’un schéma :
1
GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
Étape 1.3 : Configurer l’entrepôt et accorder l’accès au rôle Braze
Créez un entrepôt pour que Braze puisse exécuter des requêtes :
1
2
CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;
L’entrepôt doit avoir l’indicateur de reprise automatique activé. Si ce n’est pas le cas, accordez à Braze des privilèges OPERATE supplémentaires sur l’entrepôt afin que Braze puisse l’activer lors de l’exécution de la requête.
Étape 1.4 : Créer un utilisateur Snowflake
Créez un utilisateur pour Braze et attribuez-lui le rôle :
1
2
CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;
Vous utiliserez cet utilisateur lorsque vous configurerez votre source Snowflake dans Braze.
Étape 2 : Créer une nouvelle source dans le tableau de bord de Braze
Dans cette étape, créez votre source Snowflake dans Braze et validez la connexion.
Étape 2.1 : Ajouter une source Snowflake
- Dans le tableau de bord de Braze, accédez à Paramètres des données > Ingestion de données cloud > Sources.
- Sélectionnez Add data source.
- Sélectionnez Snowflake.
Étape 2.2 : Saisir les détails de connexion
Choisissez un nom pour votre source et saisissez vos identifiants et votre configuration Snowflake.
Pour le champ Snowflake Account Locator, saisissez votre identifiant de compte Snowflake, qui suit généralement un format tel que xy12345.us-east-1.aws. Ce n’est pas la même chose qu’un nom de base de données ou un nom d’entrepôt.
Étape 2.3 : Terminer la configuration de la clé RSA
Après avoir saisi vos identifiants et votre configuration, sélectionnez Save credentials et générez une clé RSA. Retournez ensuite dans Snowflake pour terminer la configuration. Ajoutez la clé publique affichée dans le tableau de bord à l’utilisateur que vous avez créé pour que Braze puisse se connecter à Snowflake.
Pour plus d’informations, consultez la documentation sur l’authentification par paire de clés Snowflake. Si vous souhaitez effectuer une rotation des clés à tout moment, Braze peut générer une nouvelle paire de clés et fournir la nouvelle clé publique.
1
ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';
De retour dans Braze, sélectionnez Test connection pour vérifier l’accès à la source, puis créez la source.
Étape 3 : Créer une nouvelle synchronisation et écrire votre requête SQL
- Accédez à Paramètres des données > Ingestion de données cloud > Syncs.
- Sélectionnez Create data sync.
- Choisissez n’importe quelle synchronisation sous Data Type.
- Référencez la source de l’étape 2.
- Sélectionnez SQL et écrivez une requête SQL qui renvoie les données utilisateur de votre entrepôt. Votre requête SQL définit les données qui se synchronisent vers Braze. Le résultat de la requête devient le schéma de votre synchronisation.
Vous pouvez utiliser l’explorateur de sources pour parcourir les tables et vues disponibles à synchroniser, ou le générateur SQL par intelligence artificielle pour obtenir l’aide de Braze Operator sur votre requête SQL.
Seules les requêtes en lecture seule sont prises en charge, y compris les clauses JOIN. Pour plus de détails, consultez Contraintes SQL.
Étape 4 : Prévisualiser et valider votre requête
Sélectionnez Preview and validate pour exécuter votre requête.
La prévisualisation :
- Affiche les résultats sous forme de tableau
- Montre jusqu’à 100 lignes
- Montre jusqu’à 250 colonnes
Pour que la validation réussisse, votre requête SQL doit renvoyer différentes colonnes requises :
| Type de données de synchronisation | Colonnes requises |
|---|---|
| Attributs | - Un identifiant utilisateur, l’un des suivants : external_id, braze_id, alias_name et alias_label, e-mail ou numéro de téléphone.- UPDATED_AT.- Au moins une colonne supplémentaire (attribut) à synchroniser. |
| Supprimer des utilisateurs | - Un identifiant utilisateur, l’un des suivants : external_id, braze_id, alias_name et alias_label, e-mail ou numéro de téléphone.- UPDATED_AT. |
| Déclencheurs Canvas | - Un identifiant utilisateur, l’un des suivants : external_id, braze_id, alias_name et alias_label, e-mail ou numéro de téléphone.- UPDATED_AT. |
| Événements personnalisés | - Un identifiant utilisateur, l’un des suivants : external_id, braze_id, alias_name et alias_label, e-mail ou numéro de téléphone.- UPDATED_AT.- NAME pour représenter le nom de l’événement.- TIME pour représenter l’heure de l’événement. Si indisponible, CDI utilise UPDATED_AT comme substitut. |
| Événements d’achat | - Un identifiant utilisateur, l’un des suivants : external_id, braze_id, alias_name et alias_label, e-mail ou numéro de téléphone.- UPDATED_AT.- PRODUCT_ID.- CURRENCY.- PRICE.- TIME pour représenter l’heure de l’événement d’achat. Si indisponible, CDI utilise UPDATED_AT comme substitut. |
| Catalogue | - ID pour représenter l’identifiant de l’élément du catalogue.- UPDATED_AT.- Au moins une colonne supplémentaire (champ de catalogue) à synchroniser. |
| Comptes | - ID pour représenter l’identifiant du compte.- NAME pour représenter le nom du compte.- UPDATED_AT.- Au moins une colonne supplémentaire (champ de compte) à synchroniser. |
Les colonnes supplémentaires en dehors des colonnes requises sont synchronisées respectivement en tant qu’attributs, propriétés de contexte Canvas, propriétés d’événement, champs de catalogue et champs de compte. Consultez Comportement de validation et Résolution des problèmes pour des conseils utiles sur les erreurs de prévisualisation et de validation et comment les corriger.
Étape 5 : Vérifier le mappage des attributs et créer la synchronisation
Lorsque la validation réussit, continuez vers Next: Notifications et créez votre synchronisation.
Une configuration SQL incorrecte peut entraîner des résultats non souhaités, y compris une surconsommation de points de données et des risques opérationnels plus larges. Vous êtes responsable de vous assurer que la logique de votre requête est correcte et devez prévisualiser attentivement tous les résultats avant d’activer une synchronisation.
Contraintes SQL
Utiliser uniquement des requêtes SELECT
Seules les requêtes en lecture seule sont prises en charge.
Vous pouvez utiliser :
SELECTWITH(CTE)JOIN
Vous ne pouvez pas utiliser :
INSERT,UPDATEouDELETECREATEouDROP- Plusieurs instructions séparées par
;
Utiliser une seule instruction
Votre requête doit être une seule instruction exécutable.
Comportement de validation
L’éditeur SQL valide votre requête avant de vous permettre de continuer.
Erreurs SQL
Si votre requête contient des erreurs de syntaxe :
- La validation échoue
- Aucune prévisualisation n’apparaît
- Votre entrepôt renvoie un message d’erreur
Erreurs de compilation
Si votre requête fait référence à des tables, colonnes ou objets invalides ou non autorisés :
- La validation échoue
- Aucune prévisualisation n’apparaît
- Votre entrepôt renvoie un message d’erreur
Erreurs de connexion
Si Braze ne peut pas se connecter à votre entrepôt :
- La validation échoue
- Aucune prévisualisation n’apparaît
- Un message d’erreur de connexion apparaît
Expiration de la requête
Si votre requête s’exécute trop longtemps :
- Braze met fin à la requête
- La validation échoue
- Une erreur d’expiration apparaît
Erreurs de schéma de table
Si votre requête compile, la validation peut tout de même échouer si :
- Aucune colonne d’identifiant n’est trouvée
UPDATED_ATest absente- D’autres colonnes requises sont manquantes
Dans ce cas, la prévisualisation apparaît tout de même pour vous aider à atteindre une validation réussie. Consultez l’étape 4 de la section précédente pour plus de détails sur les colonnes requises pour chaque type de données de synchronisation.
Résultats à zéro ligne
Si votre requête renvoie zéro ligne :
- La validation réussit
- Vous pouvez tout de même créer la synchronisation
- Aucun utilisateur n’est mis à jour tant que des lignes ne sont pas renvoyées
Prise en charge de PAYLOAD (hérité)
L’éditeur SQL prend en charge les tables CDI héritées où une colonne PAYLOAD est présente.
Si votre requête inclut :
- Un identifiant valide
UPDATED_AT- Une colonne
PAYLOAD - Des colonnes supplémentaires
Alors :
- Braze synchronise uniquement la colonne
PAYLOAD - Braze ignore les colonnes supplémentaires
Modifier une synchronisation SQL
Lors de la modification d’une synchronisation existante :
- Toute modification SQL nécessite une revalidation
- Vous ne pouvez pas enregistrer des modifications invalides
- Les modifications valides prennent effet après l’enregistrement
Si une exécution de synchronisation est déjà en cours, vos modifications prennent effet lors de la prochaine exécution.
Résolution des problèmes
Cette section présente les erreurs courantes et des conseils pour les résoudre.
Aucune prévisualisation disponible
Lorsque vous voyez « No preview available », l’un des types d’erreur sous-jacents suivants peut en être la cause.
| Type d’erreur | Étapes de résolution |
|---|---|
| « No preview available » | Lisez la bannière d’erreur pour obtenir des indices. |
| « Unable to connect to the source » | Vérifiez le nom d’utilisateur configuré, le localisateur de compte et la configuration de l’authentification par paire de clés RSA. Vérifiez que l’entrepôt est en cours d’exécution. Confirmez l’accès réseau. |
| « SQL syntax error » | Vérifiez votre syntaxe SQL. |
| « Object does not exist or not authorized » | Assurez-vous que le rôle dispose d’un accès SELECT à la table.Confirmez les autorisations de base de données et de schéma. Vérifiez les fautes de frappe dans le nom de la table. |
Colonne d’identité requise
Assurez-vous que votre requête inclut un identifiant valide, tel que external_id.
La colonne UPDATED_AT est manquante
Ajoutez une colonne d’horodatage pour la synchronisation incrémentielle.
Ajoutez plus de colonnes… Il n’y a aucun attribut/champ de catalogue/champ de compte à synchroniser
Ajoutez au moins une colonne supplémentaire en plus de l’identifiant et de UPDATED_AT.
L’exécution de la requête a expiré
Optimisez votre requête ou utilisez un entrepôt plus grand.