Cloud-Datenaufnahme: SQL-Editor
Auf dieser Seite erfahren Sie, wie Sie den SQL-Editor der Braze Cloud-Datenaufnahme (CDI) verwenden, um Synchronisierungen mit SQL-Anfragen zu erstellen und zu validieren.
Mit dem SQL-Editor der Cloud-Datenaufnahme können Sie Synchronisierungen erstellen, indem Sie SQL-Anfragen direkt für Ihr Data Warehouse schreiben. Dadurch müssen Sie keine dedizierte CDI-Tabelle mehr erstellen oder pflegen, was zuvor in Schritt 1.1 der Data-Warehouse-Integrationen erforderlich war.
Verwenden Sie den SQL-Editor, wenn Sie:
- Daten synchronisieren möchten, ohne vorgelagerte Tabellen zu ändern
- Mit Rohdaten in Ihrem Warehouse arbeiten möchten
- Die Erstellung einer
PAYLOAD-Spalte vermeiden möchten - Komplexere Datenanwendungsfälle mit SQL umsetzen möchten
Voraussetzungen und Einschränkungen
Für den SQL-Editor gelten die folgenden Einschränkungen:
- Nur für Data-Warehouse-Quellen verfügbar: Snowflake, Redshift, BigQuery, Databricks und Fabric.
- Es werden nur schreibgeschützte Abfragen mit einer einzelnen Anweisung unterstützt.
Braze führt nur schreibgeschützte Abfragen auf Ihren Daten aus und ändert Ihre zugrunde liegenden Tabellen nicht. Während der Abfrageausführung können temporäre Objekte erstellt werden, diese werden jedoch nicht dauerhaft gespeichert.
Neue SQL-Editor-Synchronisierung erstellen
Mit diesen Schritten erstellen Sie zuerst eine Quelle und anschließend eine Synchronisierung mit dem SQL-Editor. Wenn Sie bereits eine Quelle für CDI eingerichtet haben, können Sie direkt zu Schritt 3 springen.
Diese Schritte verwenden eine Snowflake-Quelle als Beispiel. Die Einrichtung anderer Data-Warehouse-Quellen läuft ähnlich ab. Sie finden sie in Schritt 2: Neue Quelle im Braze-Dashboard erstellen der Dokumentation Data-Warehouse-Integrationen einrichten.
Schritt 1: Snowflake-Rolle, Berechtigungen, Warehouse und Nutzer:in einrichten
Bevor Sie Ihre Snowflake-Quelle in CDI erstellen, stellen Sie sicher, dass der Snowflake-Nutzer bzw. die Snowflake-Nutzerin, den bzw. die Braze verwendet, Zugriff auf die abzufragenden Daten und auf ein Warehouse zum Ausführen von Abfragen hat.
Schritt 1.1: (Optional) Datenbank und Schema erstellen
Erstellen Sie bei Bedarf eine eigene Datenbank und ein eigenes Schema für Ihre CDI-Daten:
CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
Schritt 1.2: Rolle und Datenbankberechtigungen einrichten
Gewähren Sie Zugriff auf die Tabellen, die Sie synchronisieren möchten:
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;
Je nach Anwendungsfall können Sie auch Zugriff auf mehrere oder zukünftige Tabellen gewähren. So gewähren Sie beispielsweise Zugriff auf alle zukünftigen Tabellen in einem Schema:
GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
Schritt 1.3: Warehouse einrichten und der Braze-Rolle Zugriff gewähren
Erstellen Sie ein Warehouse, in dem Braze Abfragen ausführen kann:
CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;
Für das Warehouse muss das Auto-Resume-Flag aktiviert sein. Falls nicht, gewähren Sie Braze zusätzliche OPERATE-Berechtigungen für das Warehouse, damit Braze es beim Ausführen der Abfrage einschalten kann.
Schritt 1.4: Snowflake-Nutzer:in erstellen
Braze authentifiziert sich bei Snowflake entweder über Workload Identity Federation oder über ein RSA-Schlüsselpaar. Bestehende Zugangsdaten mit RSA-Schlüsselpaar funktionieren weiterhin, und Sie müssen sie nicht migrieren. Wählen Sie eine der beiden Methoden. Diese:n Nutzer:in verwenden Sie, wenn Sie Ihre Snowflake-Quelle in Braze konfigurieren.
Verwenden Sie die Rollen- und Warehouse-Berechtigungen aus Schritt 1.2 und Schritt 1.3. Erstellen Sie den Dienst-Nutzer über das Snowflake-Formular für Zugangsdaten und führen Sie diese Anweisung in einem Snowflake-Worksheet aus. Der Nutzer hat TYPE = SERVICE, kein Passwort und keinen RSA-Schlüssel. Wenn Ihr Snowflake-Konto eine Netzwerkrichtlinie verwendet, lassen Sie die IP-Adressen von Braze zu, wie in Schritt 1.5: Braze-IPs in der Snowflake-Netzwerkrichtlinie zulassen (optional) beschrieben. Was die Anweisung bewirkt und wo Sie sie ausführen, erfahren Sie unter Snowflake für Workload Identity Federation konfigurieren.
Erstellen Sie eine:n Nutzer:in für Braze und weisen Sie die Rolle zu:
CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;
Schritt 2: Neue Quelle im Braze-Dashboard erstellen
In diesem Schritt erstellen Sie Ihre Snowflake-Quelle in Braze und überprüfen die Verbindung.
Schritt 2.1: Snowflake-Quelle hinzufügen
- Gehen Sie im Braze-Dashboard zu Dateneinstellungen > Cloud-Datenaufnahme > Quellen.
- Wählen Sie Datenquelle hinzufügen.
- Wählen Sie Snowflake.
Schritt 2.2: Verbindungsdetails eingeben
Wählen Sie einen Namen für Ihre Quelle und geben Sie Ihre Snowflake-Zugangsdaten und die Konfiguration ein.
Geben Sie im Feld Snowflake-Konto-Locator Ihren Snowflake-Konto-Bezeichner ein, der typischerweise einem Format wie xy12345.us-east-1.aws folgt. Dieser ist nicht identisch mit einem Datenbank- oder Warehouse-Namen.
Schritt 2.3: Authentifizierung abschließen
Wählen Sie Workload Identity Federation oder Schlüsselpaar, passend zu dem:der Nutzer:in aus Schritt 1.4.
Geben Sie Konto-Locator, Nutzername und Rolle ein. Wählen Sie Anweisung kopieren, sobald verfügbar, führen Sie die Anweisung in einem Snowflake-Worksheet aus und wählen Sie dann Zugangsdaten speichern. Die Anweisung finden Sie unter Snowflake für Workload Identity Federation konfigurieren.
Nachdem Sie Ihre Zugangsdaten und die Konfiguration eingegeben haben, wählen Sie Zugangsdaten speichern und generieren einen RSA-Schlüssel. Kehren Sie anschließend zu Snowflake zurück, um die Einrichtung abzuschließen. Fügen Sie den im Dashboard angezeigten Public Key dem:der Nutzer:in hinzu, den bzw. die Sie für die Verbindung von Braze mit Snowflake erstellt haben.
Weitere Informationen finden Sie unter Snowflake-Schlüsselpaar-Authentifizierung. Wenn Sie die Schlüssel zu einem beliebigen Zeitpunkt rotieren möchten, kann Braze ein neues Schlüsselpaar generieren und Ihnen den neuen Public Key bereitstellen.
ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';
Wählen Sie zurück in Braze Verbindung testen, um den Zugriff auf die Quelle zu überprüfen, und erstellen Sie dann die Quelle.
Schritt 3: Neue Synchronisierung erstellen und SQL-Abfrage schreiben
- Gehen Sie zu Dateneinstellungen > Cloud-Datenaufnahme > Synchronisierungen.
- Wählen Sie Daten-Synchronisierung erstellen.
- Wählen Sie unter Datentyp eine beliebige Synchronisierung aus.
- Referenzieren Sie die Quelle aus Schritt 2.
- Wählen Sie SQL und schreiben Sie eine SQL-Abfrage, die Nutzerdaten aus Ihrem Warehouse zurückgibt. Ihre SQL-Abfrage legt fest, welche Daten mit Braze synchronisiert werden. Das Abfrageergebnis wird zum Schema für Ihre Synchronisierung.
Mit dem Source Explorer können Sie verfügbare Tabellen und Views durchsuchen, aus denen synchronisiert werden kann. Alternativ unterstützt Sie BrazeAI Operator über den KI-SQL-Generator bei Ihrer SQL-Abfrage.
Es werden nur schreibgeschützte Abfragen unterstützt, einschließlich JOIN-Klauseln. Weitere Details finden Sie unter SQL-Einschränkungen.
Schritt 4: Vorschau anzeigen und Abfrage validieren
Wählen Sie Vorschau und Validierung, um Ihre Abfrage auszuführen.
Die Vorschau:
- Zeigt die Ergebnisse in Tabellenform an
- Zeigt bis zu 100 Zeilen an
- Zeigt bis zu 250 Spalten an
Damit die Validierung erfolgreich ist, muss Ihre SQL-Abfrage verschiedene Pflichtspalten zurückgeben:
| Datentyp der Synchronisierung | Pflichtspalten |
|---|---|
| Attribute | - Ein Nutzer-Bezeichner: einer von external_id, braze_id, alias_name und alias_label, E-Mail oder Telefonnummer.- UPDATED_AT.- Mindestens eine weitere Spalte (Attribut) zum Synchronisieren. |
| Nutzer:innen löschen | - Ein Nutzer-Bezeichner: einer von external_id, braze_id, alias_name und alias_label, E-Mail oder Telefonnummer.- UPDATED_AT. |
| Canvas-Trigger | - Ein Nutzer-Bezeichner: einer von external_id, braze_id, alias_name und alias_label, E-Mail oder Telefonnummer.- UPDATED_AT. |
| Angepasste Events | - Ein Nutzer-Bezeichner: einer von external_id, braze_id, alias_name und alias_label, E-Mail oder Telefonnummer.- UPDATED_AT.- NAME für den Event-Namen.- TIME für den Event-Zeitpunkt. Falls nicht verfügbar, verwendet CDI ersatzweise UPDATED_AT. |
| Kauf-Events | - Ein Nutzer-Bezeichner: einer von external_id, braze_id, alias_name und alias_label, E-Mail oder Telefonnummer.- UPDATED_AT.- PRODUCT_ID.- CURRENCY.- PRICE.- TIME für den Zeitpunkt des Kauf-Events. Falls nicht verfügbar, verwendet CDI ersatzweise UPDATED_AT. |
| Katalog | - ID für den Bezeichner des Katalogartikels.- UPDATED_AT.- Mindestens eine weitere Spalte (Katalogfeld) zum Synchronisieren. |
| Konten | - ID für den Konto-Bezeichner.- NAME für den Kontonamen.- UPDATED_AT.- Mindestens eine weitere Spalte (Kontofeld) zum Synchronisieren. |
Zusätzliche Spalten außerhalb der Pflichtspalten werden jeweils als Attribute, Canvas-Kontexteigenschaften, Event-Eigenschaften, Katalogfelder bzw. Kontofelder synchronisiert. Unter Validierungsverhalten und Fehlerbehebung finden Sie hilfreiche Tipps zu Fehlern bei Vorschau und Validierung und wie Sie diese beheben.
Schritt 5: Attribut-Abbildung prüfen und Synchronisierung erstellen
Wenn die Validierung erfolgreich ist, fahren Sie mit Weiter: Benachrichtigungen fort und erstellen Ihre Synchronisierung.
Eine fehlerhafte SQL-Konfiguration kann zu unbeabsichtigten Ergebnissen führen, darunter ein übermäßiger Verbrauch von Datenpunkten und weitergehende betriebliche Risiken. Sie sind dafür verantwortlich, dass Ihre Abfragelogik korrekt ist, und sollten alle Ergebnisse sorgfältig in der Vorschau prüfen, bevor Sie eine Synchronisierung aktivieren.
SQL-Einschränkungen
Nur SELECT-Anfragen verwenden
Es werden nur lesende Anfragen unterstützt.
Sie können verwenden:
SELECTWITH(CTEs)JOIN
Sie können nicht verwenden:
INSERT,UPDATEoderDELETECREATEoderDROP- Mehrere Anweisungen, getrennt durch
;
Eine einzelne Anweisung verwenden
Ihre Anfrage muss eine einzelne ausführbare Anweisung sein.
Validierungsverhalten
Der SQL-Editor validiert Ihre Anfrage, bevor Sie fortfahren können.
SQL-Fehler
Wenn Ihre Anfrage Syntaxfehler enthält:
- Die Validierung schlägt fehl
- Es wird keine Vorschau angezeigt
- Ihr Warehouse gibt eine Fehlermeldung zurück
Kompilierungsfehler
Wenn Ihre Anfrage auf ungültige Tabellen, Spalten oder nicht autorisierte Objekte verweist:
- Die Validierung schlägt fehl
- Es wird keine Vorschau angezeigt
- Ihr Warehouse gibt eine Fehlermeldung zurück
Verbindungsfehler
Wenn Braze keine Verbindung zu Ihrem Warehouse herstellen kann:
- Die Validierung schlägt fehl
- Es wird keine Vorschau angezeigt
- Eine Verbindungsfehlermeldung wird angezeigt
Anfrage-Timeout
Wenn Ihre Anfrage zu lange läuft:
- Braze beendet die Anfrage
- Die Validierung schlägt fehl
- Ein Timeout-Fehler wird angezeigt
Tabellenschema-Fehler
Wenn Ihre Anfrage kompiliert wird, kann die Validierung dennoch fehlschlagen, wenn:
- Keine Bezeichner-Spalte gefunden wird
UPDATED_ATfehlt- Andere erforderliche Spalten fehlen
In diesem Fall wird die Vorschau dennoch angezeigt, um Ihnen bei einer erfolgreichen Validierung zu helfen. Details zu den erforderlichen Spalten für jeden Synchronisierungsdatentyp finden Sie unter Schritt 4 im vorherigen Abschnitt.
Ergebnisse mit null Zeilen
Wenn Ihre Anfrage null Zeilen zurückgibt:
- Die Validierung ist erfolgreich
- Sie können die Synchronisierung trotzdem erstellen
- Es werden keine Nutzer:innen aktualisiert, bis Zeilen zurückgegeben werden
PAYLOAD-Unterstützung (Legacy)
Der SQL Editor unterstützt Legacy-CDI-Tabellen, die eine PAYLOAD-Spalte enthalten.
Wenn Ihre Abfrage Folgendes enthält:
- Einen gültigen Bezeichner
UPDATED_AT- Eine
PAYLOAD-Spalte - Zusätzliche Spalten
Dann gilt:
- Braze synchronisiert nur die
PAYLOAD-Spalte - Braze ignoriert zusätzliche Spalten
SQL-Synchronisierung bearbeiten
Beim Bearbeiten einer bestehenden Synchronisierung gilt:
- Jede SQL-Änderung erfordert eine erneute Validierung
- Ungültige Änderungen können Sie nicht speichern
- Gültige Änderungen werden nach dem Speichern wirksam
Wenn bereits ein Synchronisierungslauf ausgeführt wird, werden Ihre Änderungen beim nächsten Lauf wirksam.
Fehlerbehebung
In diesem Abschnitt finden Sie häufige Fehler und Hinweise, wie Sie diese beheben.
„Keine Vorschau verfügbar“
Wenn „Keine Vorschau verfügbar“ angezeigt wird, kann einer der folgenden zugrunde liegenden Fehlertypen die Ursache sein.
| Fehlertyp | Schritte zur Behebung |
|---|---|
| „Keine Vorschau verfügbar“ | Lesen Sie das Fehlerbanner, um Hinweise zu erhalten. |
| „Verbindung zur Quelle nicht möglich“ | Überprüfen Sie den konfigurierten Nutzernamen, den Account Locator und die Authentifizierungsmethode. Stellen Sie bei einem Schlüsselpaar sicher, dass der öffentliche RSA-Schlüssel beim Snowflake-Nutzer hinterlegt ist. Stellen Sie bei Workload Identity Federation sicher, dass Sie die Anweisung aus dem Formular für die Zugangsdaten ausgeführt haben. Überprüfen Sie, ob das Warehouse läuft. Bestätigen Sie den Netzwerkzugriff. |
| „SQL-Syntaxfehler“ | Überprüfen Sie Ihre SQL-Syntax. |
| „Objekt existiert nicht oder nicht autorisiert“ | Stellen Sie sicher, dass die Rolle SELECT-Zugriff auf die Tabelle hat.Bestätigen Sie die Datenbank- und Schemaberechtigungen. Überprüfen Sie den Tabellennamen auf Tippfehler. |
„Bezeichner-Spalte erforderlich“
Stellen Sie sicher, dass Ihre Anfrage einen gültigen Bezeichner enthält, wie z. B. external_id.
„UPDATED_AT-Spalte fehlt“
Fügen Sie eine Zeitstempel-Spalte für die inkrementelle Synchronisierung hinzu.
„Weitere Spalten hinzufügen … Es sind keine Attribute/Katalogfelder/Kontofelder zum Synchronisieren vorhanden“
Fügen Sie neben dem Bezeichner und UPDATED_AT mindestens eine weitere Spalte hinzu.
„Zeitlimit für Anfrageausführung überschritten“
Optimieren Sie Ihre Anfrage oder verwenden Sie ein größeres Warehouse.