Best Practices

Mit Braze Cloud Data Ingestion können Sie eine direkte Verbindung von Ihrem Data Warehouse oder Dateispeichersystem zu Braze einrichten, um relevante Nutzer- oder Katalogdaten zu synchronisieren. Wenn Sie diese Daten mit Braze synchronisieren, können Sie sie für Anwendungsfälle wie Personalisierung, Triggern oder Segmentierung nutzen.

Änderungen mit UPDATED_AT nachverfolgen

Hinweis

UPDATED_AT ist nur für Data-Warehouse-Integrationen relevant, nicht für Dateispeicher-Synchronisierungen.

Wenn eine Synchronisierung ausgeführt wird, stellt Braze eine direkte Verbindung zu Ihrer Data-Warehouse-Instanz her und verwendet den UPDATED_AT-Zeitstempel jeder Zeile zur Änderungsverfolgung. UPDATED_AT ist ein Pflichtfeld für alle Data-Warehouse-Synchronisierungen.

Wichtig

CDI verfolgt Änderungen ausschließlich auf Basis der UPDATED_AT-Werte, unabhängig davon, ob der Zeileninhalt mit dem übereinstimmt, was derzeit in Braze vorhanden ist. Braze empfiehlt, UPDATED_AT zu verwenden, um nur neue oder aktualisierte Daten zu synchronisieren, um unnötige Datenpunkt-Nutzung zu vermeiden.

Beispiel: Verhalten einer wiederkehrenden Synchronisierung

Um zu veranschaulichen, wie UPDATED_AT in einer CDI-Synchronisierung verwendet wird, betrachten Sie dieses Beispiel einer wiederkehrenden Synchronisierung zur Aktualisierung von Nutzerattributen.

Bei jeder Synchronisierung sucht CDI nach Zeilen, die zuvor noch nicht synchronisiert wurden. CDI prüft dies anhand der UPDATED_AT-Spalte in Ihrer Tabelle oder Ansicht. Braze wählt alle Zeilen aus und importiert sie, deren UPDATED_AT-Wert neuer ist als der zuletzt synchronisierte UPDATED_AT-Wert. Zeilen an der exakten Grenz-Zeitstempel-Grenze können ebenfalls erneut synchronisiert werden, wenn zwischen den Durchläufen neue Zeilen mit demselben Zeitstempel hinzugefügt werden.

Wichtig

CDI verfolgt die Anzahl der Zeilen mit dem zuletzt synchronisierten UPDATED_AT-Wert. Wenn zwischen den Durchläufen neue Zeilen mit demselben Zeitstempel hinzugefügt werden, wechselt CDI zu einer inklusiven Grenze (>=) und synchronisiert alle Zeilen mit diesem Zeitstempel erneut, einschließlich bereits verarbeiteter Zeilen. Um doppelte Synchronisierungen und unnötige Datenpunkt-Nutzung zu vermeiden, verwenden Sie eindeutige UPDATED_AT-Werte über die Synchronisierungsdurchläufe hinweg. Weitere Informationen finden Sie unter Erneutes Synchronisieren von Zeilen mit doppelten Zeitstempeln vermeiden.

Fügen Sie in Ihrem Data Warehouse die folgenden Nutzer:innen und Attribute zu Ihrer Tabelle hinzu und setzen Sie die UPDATED_AT-Zeit auf den Zeitpunkt, zu dem Sie diese Daten hinzufügen:

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_1"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

Bei der nächsten geplanten Synchronisierung synchronisiert Braze alle Zeilen mit einem UPDATED_AT-Zeitstempel, der neuer ist als der zuletzt synchronisierte Zeitstempel. Braze aktualisiert oder ergänzt Felder, sodass Sie nicht jedes Mal das vollständige Nutzerprofil synchronisieren müssen. Nach der Synchronisierung spiegeln die Nutzerprofile die neuen Aktualisierungen wider:

Wiederkehrende Synchronisierung, zweiter Durchlauf am 20. Juli 2022 um 12 Uhr

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_2",
        "attribute_b":"example_value_2"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":false,
    "attribute_5":"testing_123"
}

Eine neue Zeile wurde für customer_9012 hinzugefügt, aber der UPDATED_AT-Wert (2022-07-16 00:25:30) liegt vor dem gespeicherten Zeitstempel (2022-07-19 09:07:23), sodass diese Zeile nicht synchronisiert wird. Die bestehende Zeile für customer_5678 hat jedoch einen UPDATED_AT-Wert, der dem gespeicherten Zeitstempel entspricht, und wird daher aufgrund der inklusiven Grenze erneut synchronisiert. Weitere Details zu diesem Verhalten finden Sie unter Erneutes Synchronisieren von Zeilen mit doppelten Zeitstempeln vermeiden. Der gespeicherte UPDATED_AT-Wert bleibt 2022-07-19 09:07:23.

Wiederkehrende Synchronisierung, dritter Durchlauf am 21. Juli 2022 um 12 Uhr

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_1"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

1
2
3
4
5

{
    "attribute_1":"xyz",
    "attribute_4":false,
    "attribute_5":"testing_123"
}

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_2",
        "attribute_b":"example_value_2"
    },
    "attribute_3":"2019-07-20T19:20:30+1:00"
}

In diesem dritten Durchlauf wurde eine weitere neue Zeile für customer_1234 mit einem UPDATED_AT-Wert (2022-07-21 08:30:00) hinzugefügt, der neuer ist als der gespeicherte Zeitstempel. Diese neue Zeile und die bestehende Zeile für customer_5678 (deren UPDATED_AT-Wert dem gespeicherten Zeitstempel entspricht) werden beide synchronisiert. Der gespeicherte UPDATED_AT-Wert wird nun auf 2022-07-21 08:30:00 gesetzt.

Hinweis

UPDATED_AT-Werte dürfen auch nach dem Startzeitpunkt eines bestimmten Synchronisierungsdurchlaufs liegen. Dies wird jedoch nicht empfohlen, da der letzte UPDATED_AT-Zeitstempel dadurch „in die Zukunft“ verschoben wird und nachfolgende Synchronisierungen keine früheren Werte synchronisieren werden.

Datentyp-Probleme vermeiden

Wenn Sie CDI verwenden, um Daten aus externen Quellen (wie Databricks oder Snowflake) zu synchronisieren, stellen Sie vor der Synchronisierung sicher, dass Ihre Quellspalten die richtigen Datentypen verwenden. Häufige Probleme sind:

• Zeitstempel als Strings gespeichert: Stellen Sie sicher, dass Ihre Datumsspalten in Ihrer Quelldatenbank einen Timestamp- oder Datetime-Typ verwenden und keinen Varchar- oder String-Typ.
• Zahlen als Strings gespeichert: Wandeln Sie numerische Spalten in Ihrer Quellabfrage vor der Synchronisierung in Integer- oder Float-Typen um.
• Inkonsistente Typen zwischen Synchronisierungen: Wenn sich der Typ einer Spalte zwischen Synchronisierungen ändert, lehnt Braze die neuen Daten möglicherweise ab. Überprüfen Sie, dass Ihr Quellschema konsistent bleibt.

Informationen zum Erzwingen oder Ändern von Datentypen für angepasste Attribute im Braze-Dashboard finden Sie unter Angepasste Daten verwalten.

Sie können Nutzerdaten über externe ID, Nutzer-Alias, Braze-ID, E-Mail oder Telefonnummer aktualisieren. Nutzer:innen können Sie über externe ID, Nutzer-Alias oder Braze-ID löschen.

UTC-Zeitstempel für die Spalte UPDATED_AT verwenden

Die Spalte UPDATED_AT sollte in UTC angegeben sein, um Probleme mit der Sommerzeit zu vermeiden. Verwenden Sie nach Möglichkeit reine UTC-Funktionen, beispielsweise SYSDATE() statt CURRENT_DATE().

Erneutes Synchronisieren von Zeilen mit doppelten Zeitstempeln vermeiden

CDI verfolgt die Anzahl der Zeilen beim zuletzt synchronisierten UPDATED_AT-Zeitstempel. Wenn CDI erkennt, dass seit dem letzten Durchlauf neue Zeilen mit demselben Zeitstempel hinzugefügt wurden, verwendet es eine inklusive Grenze (>=), um alle Zeilen mit diesem Zeitstempel erneut auszuwählen, einschließlich bereits verarbeiteter. Andernfalls verwendet CDI eine exklusive Grenze (>) und wählt nur Zeilen aus, die strikt nach dem zuletzt synchronisierten Wert liegen.

Wenn beispielsweise eine Synchronisierung fünf Zeilen mit UPDATED_AT = 2025-04-01 00:00:00 verarbeitet und später eine sechste Zeile mit demselben Zeitstempel hinzugefügt wird, erkennt die nächste Synchronisierung die Änderung der Anzahl und synchronisiert alle sechs Zeilen erneut. Dies kann zu doppelten Daten und unnötigem Datenpunktverbrauch führen.

Um dies zu vermeiden:

• Wenn Sie eine Synchronisierung gegen eine VIEW einrichten, verwenden Sie nicht CURRENT_TIMESTAMP als Standardwert. Dies führt dazu, dass alle Daten bei jedem Synchronisierungslauf synchronisiert werden, da das UPDATED_AT-Feld zum Zeitpunkt der Abfrageausführung ausgewertet wird.
• Wenn Sie lang laufende Pipelines oder Abfragen haben, die Daten in Ihre Quelltabelle schreiben, vermeiden Sie es, diese gleichzeitig mit einer Synchronisierung auszuführen, oder vermeiden Sie es, denselben Zeitstempel für jede eingefügte Zeile zu verwenden.
• Verwenden Sie eine Transaktion, um alle Zeilen zu schreiben, die denselben Zeitstempel haben.
• Verwenden Sie eindeutige, monoton steigende UPDATED_AT-Werte, um zu verhindern, dass Zeilen nach der Verarbeitung erneut ausgewählt werden.

Beispiel: Verwaltung nachfolgender Updates

Dieses Beispiel zeigt den allgemeinen Prozess für die erstmalige Synchronisierung von Daten und die anschließende Aktualisierung nur der geänderten Daten (Deltas) in den nachfolgenden Updates. Nehmen wir an, wir haben eine Tabelle EXAMPLE_DATA mit einigen Nutzerdaten. Am Tag 1 hat sie die folgenden Werte:

Um diese Daten in eine PAYLOAD-Spalte zu überführen, könnten Sie die folgende Abfrage ausführen:

1
2
3
4
5
6
7
8
9
10
11
12

SELECT
    CURRENT_TIMESTAMP AS UPDATED_AT,
    EXTERNAL_ID AS EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT(
            'attribute_1', attribute_1,
            'attribute_2', attribute_2,
            'attribute_3', attribute_3,
            'attribute_4', attribute_4
        )
    ) AS PAYLOAD
FROM EXAMPLE_DATA;

Nichts davon wurde bisher mit Braze synchronisiert, also fügen Sie alles der Quelltabelle für CDI hinzu:

Eine Synchronisierung wird durchgeführt und Braze hält fest, dass Sie alle verfügbaren Daten bis zum Zeitpunkt „2023-03-16 15:00:00“ synchronisiert haben. Am Morgen des 2. Tages wird dann ein ETL ausgeführt und einige Felder in Ihrer Nutzertabelle werden aktualisiert (mit * gekennzeichnet):

Jetzt müssen Sie nur noch die geänderten Werte in die CDI-Quelltabelle einfügen. Diese Zeilen können angehängt werden, anstatt die alten Zeilen zu aktualisieren. Die Tabelle sieht nun wie folgt aus:

CDI synchronisiert nur die neuen Zeilen. Bei der nächsten Synchronisierung werden also nur die letzten fünf Zeilen synchronisiert.

Zusätzliche Tipps

Nur neue oder aktualisierte Attribute schreiben, um den Verbrauch zu minimieren

Bei jeder Synchronisierung sucht Braze nach Zeilen, die noch nicht synchronisiert wurden. Dazu prüfen wir die Spalte UPDATED_AT in Ihrer Tabelle oder Ansicht. Braze wählt alle Zeilen aus, deren UPDATED_AT nach dem zuletzt synchronisierten UPDATED_AT-Wert liegt, und importiert sie. Dabei spielt es keine Rolle, ob sie mit den aktuellen Werten im Nutzerprofil übereinstimmen. Zeilen mit dem Grenz-Zeitstempel werden unter Umständen erneut synchronisiert, wenn neue Zeilen denselben Zeitstempel haben. Wir empfehlen daher, nur Attribute zu synchronisieren, die Sie hinzufügen oder aktualisieren möchten.

Die Datenpunkt-Nutzung ist bei CDI identisch mit anderen Methoden der Datenaufnahme wie REST APIs oder SDKs. Sie sind also selbst dafür verantwortlich, nur neue oder aktualisierte Attribute in Ihre Quelltabellen zu schreiben.

EXTERNAL_ID von der Spalte PAYLOAD trennen

Das Objekt PAYLOAD sollte keine externe ID und keinen anderen ID-Typ enthalten.

Ein Attribut entfernen

In einer PAYLOAD-Spalte können Sie ein Attribut auf null setzen, wenn Sie es aus dem Profil von Nutzer:innen weglassen möchten. Wenn ein Attribut unverändert bleiben soll, senden Sie es erst an Braze, wenn es aktualisiert wurde. Um ein Attribut vollständig zu entfernen, verwenden Sie TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Inkrementelle Updates durchführen

Aktualisieren Sie Ihre Daten inkrementell, um unbeabsichtigtes Überschreiben bei gleichzeitigen Updates zu vermeiden.

Wichtig

• Updates verschiedener Attribute: In den allermeisten Fällen haben zwei Updates, die nicht dieselben Attribute eines Nutzers oder einer Nutzerin betreffen, völlig unabhängige Ergebnisse. Wenn Sie zum Beispiel das Attribut Color und separat das Attribut Size aktualisieren, sollten beide Updates korrekt angewendet werden, selbst wenn sie innerhalb weniger Sekunden erfolgen.
• Updates desselben Attributs: Race-Conditions können auftreten, wenn mehrere Updates innerhalb eines einzigen Synchronisierungslaufs dasselbe Attribut betreffen. In diesen seltenen Fällen kann ein Update ein anderes überschreiben. Am besten verhindern Sie dieses Verhalten, indem Sie sicherstellen, dass die Quelldaten Ihrer CDI-Synchronisierung nur den neuesten Stand jedes Nutzers bzw. jeder Nutzerin widerspiegeln oder dass alle Updates für eine bestimmte Nutzer:in oder eine Kombination aus Nutzer:in und Attribut in einer einzigen Zeile enthalten sind.
• Objekt-Array-Operatoren: Die einzigen Ausnahmen von unabhängigen Updates sind die Operatoren $add, $remove und $update für Objekt-Arrays, bei denen sich Updates desselben Arrays gegenseitig beeinflussen können.
• Events: Race-Conditions wirken sich nicht auf Events aus, da jedes Event eindeutig ist und einen zugehörigen Zeitstempel hat.

Am besten verhindern Sie dieses Verhalten, indem Sie sicherstellen, dass die Quelldaten Ihrer CDI-Synchronisierung nur den neuesten Stand jedes Nutzers bzw. jeder Nutzerin widerspiegeln oder dass alle Updates für eine bestimmte Nutzer:in oder eine Kombination aus Nutzer:in und Attribut in einer einzigen Zeile enthalten sind.

Einen JSON-String aus einer anderen Tabelle erstellen

Wenn Sie eine PAYLOAD-Spalte verwenden und jedes Attribut intern in einer eigenen Spalte speichern, konvertieren Sie diese Spalten in einen JSON-String, um PAYLOAD zu befüllen. Um separate Spalten ohne JSON-String zu synchronisieren, verwenden Sie stattdessen die Option Visual oder SQL. Weitere Informationen finden Sie unter Option für die Datendefinition auswählen.

Jede Quellseite enthält ein ausgearbeitetes Beispiel im SQL-Dialekt des jeweiligen Data Warehouse:

• Snowflake
• Amazon Redshift
• Google BigQuery
• Databricks
• Microsoft Fabric

Zum Beispiel in Snowflake:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    )as PAYLOAD FROM "EXAMPLE_USER_DATA";

Den Zeitstempel UPDATED_AT verwenden

Braze verwendet den Zeitstempel UPDATED_AT, um nachzuverfolgen, welche Daten erfolgreich synchronisiert wurden. CDI erfasst außerdem die Anzahl der Zeilen beim zuletzt synchronisierten Zeitstempel. Werden zwischen zwei Läufen neue Zeilen mit demselben Zeitstempel hinzugefügt, synchronisiert CDI alle Zeilen mit diesem Zeitstempel erneut, was zu doppelten Daten führen kann. Weitere Details und Tipps finden Sie unter Erneute Synchronisierung von Zeilen mit doppelten Zeitstempeln vermeiden.

Tabellenkonfiguration

Wir haben ein öffentliches GitHub-Repository, in dem Kund:innen Best Practices oder Code-Snippets teilen können. Um eigene Snippets beizutragen, erstellen Sie einen Pull-Request!

Datenformatierung

Die Anforderungen an die Tabelleneinrichtung und an die Payload-Formatierung für Cloud Data Ingestion sind unter Tabelleneinrichtung für Cloud Data Ingestion dokumentiert.

Auf dieser Seite können Sie folgende Punkte unterscheiden:

• Anforderungen an die Quelltabelle (erforderliche Spalten, Bezeichner-Spalten und Verhalten von UPDATED_AT)
• Anforderungen an die Payload (welche Felder für jeden Datentyp dem Objektformat von /users/track entsprechen müssen)

Timeouts bei Data-Warehouse-Abfragen vermeiden

Wir empfehlen, dass Abfragen innerhalb einer Stunde abgeschlossen werden, um eine optimale Performance zu erzielen und mögliche Fehler zu vermeiden. Wenn Abfragen diesen Zeitrahmen überschreiten, sollten Sie die Konfiguration Ihres Data Warehouse überprüfen. Eine Optimierung der Ressourcen, die Ihrem Warehouse zugewiesen sind, kann die Ausführungsgeschwindigkeit von Abfragen verbessern.

Produktbeschränkungen