Skip to content

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

Conditions préalables et limitations

Pendant la bêta, l’éditeur SQL présente les limitations suivantes :

  • Disponible uniquement pour les synchronisations d’attributs utilisateur
  • Prend en charge une seule source d’entrepôt : Snowflake

Créer une nouvelle synchronisation avec l’éditeur SQL

Suivez ces étapes pour créer une synchronisation avec l’éditeur SQL. Si vous avez déjà configuré une source Snowflake pour CDI, passez à l’étape 3.

É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;

É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

  1. Dans le tableau de bord de Braze, accédez à Data Settings > Cloud Data Ingestion > Sources.
  2. Sélectionnez Add data source.
  3. 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.

É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

  1. Accédez à Data Settings > Cloud Data Ingestion > Syncs.
  2. Sélectionnez Create data sync.
  3. Choisissez User Attributes sous Data Type.
  4. Référencez la source Snowflake de l’étape 2.
  5. 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.

Le flux de création de synchronisation de données montrant SQL sélectionné avec un exemple de requête dans l'éditeur SQL.

Votre requête SQL doit renvoyer :

  • Un identifiant utilisateur (EXTERNAL_ID, BRAZE_ID, ALIAS_NAME et ALIAS_LABEL, EMAIL ou PHONE)
  • Une colonne UPDATED_AT
  • Au moins une colonne supplémentaire (attribut)

É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

Vous devez prévisualiser et valider votre requête avec succès avant de continuer. Pour plus de détails sur les erreurs et les corrections, consultez Comportement de validation et Résolution des problèmes.

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

Après la validation :

  • La colonne d’identifiant fait correspondre les utilisateurs
  • La colonne UPDATED_AT pilote la synchronisation incrémentielle
  • Braze synchronise toutes les autres colonnes en tant qu’attributs

Lorsque la validation réussit, continuez vers Next: Notifications et créez votre synchronisation.

Contraintes SQL

Votre requête doit respecter les exigences suivantes.

Inclure un identifiant utilisateur

Votre requête doit inclure au moins l’un des éléments suivants :

  • EXTERNAL_ID
  • BRAZE_ID
  • EMAIL
  • PHONE
  • ALIAS_NAME et ALIAS_LABEL

Si aucun identifiant valide n’est détecté, la validation échoue.

Inclure UPDATED_AT

Votre requête doit inclure une colonne UPDATED_AT.

UPDATED_AT est sensible à la casse et doit être en majuscules.

Si elle est absente, la validation échoue.

Inclure au moins une colonne d’attribut

Votre requête doit inclure au moins une colonne en plus de :

  • La ou les colonnes d’identifiant utilisateur
  • UPDATED_AT

Sinon, la validation échoue.

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

Colonnes requises manquantes

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
  • Aucune colonne d’attribut n’est présente

Dans ce cas, la prévisualisation apparaît tout de même pour vous aider à atteindre une validation réussie.

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.

Aucun attribut à 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.
New Stuff!