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 erforderlich war, wenn Sie eine Quelltabelle eingerichtet haben.

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.

Hinweis

Braze führt ausschließlich schreibgeschützte Abfragen auf Ihren Daten aus und verändert Ihre zugrunde liegenden Tabellen nicht. Während der Abfrageausführung können temporäre Objekte erstellt werden, die jedoch nicht dauerhaft gespeichert werden.

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 mit Schritt 3 fortfahren.

Hinweis

In diesen Schritten dient eine Snowflake-Quelle als Beispiel. Die Einrichtung anderer Data-Warehouse-Quellen läuft ähnlich ab. Eine Anleitung finden Sie auf der jeweiligen Seite unter Quellen für Cloud-Datenaufnahme.

Schritt 1: Snowflake-Rolle, Berechtigungen, Warehouse und Nutzer:in einrichten

Bevor Sie Ihre Snowflake-Quelle in CDI erstellen, stellen Sie sicher, dass die Snowflake-Nutzer:in, 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:

1
2

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:

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;

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:

1

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:

1
2

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

Hinweis

Für das Warehouse muss das Auto-Resume-Flag aktiviert sein. Ist das nicht der Fall, gewähren Sie Braze zusätzlich OPERATE-Berechtigungen für das Warehouse, damit Braze es beim Ausführen der Abfrage einschalten kann.

Schritt 1.4: Snowflake-Nutzer:in erstellen

Erstellen Sie eine Nutzer:in für Braze und weisen Sie ihr die Rolle zu:

1
2

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Diese Nutzer:in verwenden Sie, wenn Sie Ihre Snowflake-Quelle in Braze konfigurieren.

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

1. Gehen Sie im Braze-Dashboard zu Dateneinstellungen > Cloud-Datenaufnahme > Quellen.
2. Wählen Sie Datenquelle hinzufügen aus.
3. Wählen Sie Snowflake aus.

Schritt 2.2: Verbindungsdetails eingeben

Wählen Sie einen Namen für Ihre Quelle und geben Sie Ihre Snowflake-Zugangsdaten und -Konfiguration ein.

Hinweis

Geben Sie im Feld Snowflake Account Locator Ihren Snowflake-Konto-Bezeichner ein, der in der Regel einem Format wie xy12345.us-east-1.aws folgt. Dieser ist nicht identisch mit einem Datenbank- oder Warehouse-Namen.

Schritt 2.3: RSA-Schlüssel einrichten

Nachdem Sie Ihre Zugangsdaten und Konfiguration eingegeben haben, wählen Sie Zugangsdaten speichern aus und generieren Sie einen RSA-Schlüssel. Wechseln Sie dann zurück zu Snowflake, um die Einrichtung abzuschließen. Fügen Sie den im Dashboard angezeigten Public Key der Nutzer:in hinzu, 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.

1

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

Wählen Sie anschließend in Braze Verbindung testen aus, um den Zugriff auf die Quelle zu überprüfen, und erstellen Sie dann die Quelle.

Schritt 3: Neue Synchronisierung erstellen und SQL-Abfrage schreiben

1. Gehen Sie zu Dateneinstellungen > Cloud-Datenaufnahme > Synchronisierungen.
2. Wählen Sie Daten-Synchronisierung erstellen aus.
3. Wählen Sie unter Datentyp eine beliebige Synchronisierung aus.
4. Verweisen Sie auf die Quelle aus Schritt 2.
5. Wählen Sie SQL aus 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 Ihrer Synchronisierung.

Mit dem Source Explorer können Sie nach verfügbaren Tabellen und Views suchen, aus denen synchronisiert werden kann. Alternativ unterstützt Sie BrazeAI Operator über den KI-SQL-Generator bei Ihrer SQL-Abfrage.

Hinweis

Es werden nur Leseabfragen 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 validieren aus, 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

Für eine erfolgreiche Validierung muss Ihre SQL-Abfrage verschiedene Pflichtspalten zurückgeben:

Zusätzliche Spalten außerhalb der Pflichtspalten werden entsprechend 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 deren Behebung.

Schritt 5: Attribut-Abbildung prüfen und Synchronisierung erstellen

Wenn die Validierung erfolgreich ist, fahren Sie mit Weiter: Benachrichtigungen fort und erstellen Sie Ihre Synchronisierung.

Wichtig

Eine fehlerhafte SQL-Konfiguration kann zu unbeabsichtigten Ergebnissen führen, darunter ein übermäßiger Verbrauch von Datenpunkten und weitreichendere 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:

• SELECT
• WITH (CTEs)
• JOIN

Sie können nicht verwenden:

• INSERT, UPDATE oder DELETE
• CREATE oder DROP
• 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_AT fehlt
• 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

Eine SQL-Synchronisierung bearbeiten

Wenn Sie eine bestehende Synchronisierung bearbeiten, gilt Folgendes:

• Jede Änderung am SQL 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.

„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.