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. Vous n’avez donc plus besoin de créer ni de maintenir une table CDI dédiée, ce qui était auparavant requis à 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’usage de données plus complexes avec SQL

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 composées d’une seule instruction sont prises en charge.

Remarque

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 ils 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 la CDI, passez directement à l’étape 3.

Remarque

Ces étapes prennent l’exemple d’une source Snowflake. Le processus de configuration des autres sources d’entrepôt de données est similaire. Vous le trouverez à l’étape 2 : Créer une nouvelle source dans le tableau de bord de Braze de la documentation Configuration des intégrations d’entrepôts 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 la CDI, assurez-vous que l’utilisateur Snowflake utilisé par Braze a accès aux données que vous souhaitez interroger et dispose d’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 à 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 la 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;

Selon votre cas d’usage, vous pouvez aussi accorder l’accès à plusieurs tables ou aux tables futures. 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 dans lequel Braze exécutera les requêtes :

1
2

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

Remarque

L’option de reprise automatique (auto-resume) doit être activée sur l’entrepôt. Sinon, 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

Braze s’authentifie auprès de Snowflake à l’aide de la fédération d’identité de charge de travail (Workload Identity Federation) ou d’une paire de clés RSA. Les identifiants par paire de clés RSA existants continuent de fonctionner, et vous n’avez pas besoin de les migrer. Suivez l’une des deux méthodes. Vous utiliserez cet utilisateur lors de la configuration de votre source Snowflake dans Braze.

• workload identity federation
• paire de clés

1
2

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

É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

1. Dans le tableau de bord de Braze, allez dans Paramètres des données > Ingestion de données cloud > Sources.
2. Sélectionnez Ajouter une source de données.
3. Sélectionnez Snowflake.

Étape 2.2 : Saisir les détails de connexion

Choisissez un nom pour votre source, puis saisissez vos identifiants et votre configuration Snowflake.

Remarque

Dans le champ Localisateur de compte Snowflake, saisissez votre identifiant de compte Snowflake, qui suit généralement un format du type xy12345.us-east-1.aws. Il ne s’agit ni du nom d’une base de données ni de celui d’un entrepôt.

Étape 2.3 : Terminer l’authentification

Sélectionnez Workload Identity Federation ou Paire de clés selon l’utilisateur créé à l’étape 1.4.

• workload identity federation
• paire de clés

1

ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';

De retour dans Braze, sélectionnez Tester la connexion pour vérifier l’accès à la source, puis créez la source.

Étape 3 : Créer une nouvelle synchronisation et rédiger votre requête SQL

1. Allez dans Paramètres des données > Ingestion de données cloud > Synchronisations.
2. Sélectionnez Créer une synchronisation de données.
3. Choisissez n’importe quelle synchronisation sous Type de données.
4. Référencez la source créée à l’étape 2.
5. Sélectionnez SQL et rédigez une requête SQL qui renvoie les données utilisateur de votre entrepôt. Votre requête SQL définit les données synchronisées avec 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 les vues disponibles à synchroniser, ou le générateur SQL par IA pour obtenir l’aide de Braze Operator sur votre requête SQL.

Remarque

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 Prévisualiser et valider pour exécuter votre requête.

L’aperçu :

• Affiche les résultats sous forme de tableau
• Affiche jusqu’à 100 lignes
• Affiche jusqu’à 250 colonnes

Pour être validée, votre requête SQL doit renvoyer plusieurs colonnes obligatoires :

Les colonnes supplémentaires, en dehors des colonnes obligatoires, 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 obtenir des conseils utiles sur les erreurs de prévisualisation et de validation, et sur la manière de les corriger.

Étape 5 : Vérifier le mappage des attributs et créer la synchronisation

Une fois la validation réussie, passez à Suivant : Notifications et créez votre synchronisation.

Important

Une configuration SQL inexacte peut entraîner des résultats inattendus, notamment une surconsommation de points de données et des risques opérationnels plus larges. Il vous incombe de vérifier que la logique de votre requête est correcte et de 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 :

• SELECT
• WITH (CTE)
• JOIN

Vous ne pouvez pas utiliser :

• INSERT, UPDATE ou DELETE
• CREATE ou DROP
• 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_AT est 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 (ancienne version)

L’éditeur SQL prend en charge les anciennes tables CDI qui contiennent une colonne PAYLOAD.

Si votre requête comprend :

• 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

Lorsque vous modifiez une synchronisation existante :

• Toute modification SQL nécessite une nouvelle validation
• Vous ne pouvez pas enregistrer des modifications non valides
• Les modifications valides prennent effet après l’enregistrement

Si une synchronisation est déjà en cours d’exécution, vos modifications prendront effet lors de la prochaine exécution.

Résolution des problèmes

Cette section présente les erreurs courantes et explique comment les résoudre.

Aucune prévisualisation disponible

Si le message « No preview available » s’affiche, l’un des types d’erreur sous-jacents suivants peut en être la cause.

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.