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.

Die Spalte UPDATED_AT verstehen

Hinweis

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

Wenn eine Synchronisierung ausgeführt wird, stellt Braze eine direkte Verbindung zu Ihrer Data-Warehouse-Instanz her, ruft alle neuen Daten aus der angegebenen Tabelle ab und aktualisiert die entsprechenden Daten in Ihrem Braze-Dashboard. Bei jeder Ausführung der Synchronisierung spiegelt Braze alle aktualisierten Daten wider.

Wichtig

Braze CDI synchronisiert Zeilen ausschließlich auf Basis des UPDATED_AT-Werts, unabhängig davon, ob der Zeileninhalt mit dem übereinstimmt, was derzeit in Braze vorhanden ist. Daher empfehlen wir, UPDATED_AT korrekt zu verwenden, um nur neue oder aktualisierte Daten zu synchronisieren und unnötige Datenpunkt-Nutzung zu vermeiden.

Beispiel: Wiederkehrende Synchronisierung

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

• Dateispeicher-Quellen
  • Amazon S3

Unterstützte Datentypen

Cloud Data Ingestion unterstützt die folgenden Datentypen:

• Nutzerattribute, einschließlich:
  • Verschachtelte angepasste Attribute
  • Objekt-Arrays
  • Abo-Status
• Angepasste Events
• Kauf-Events
• Katalogartikel
• Löschanfragen für Nutzer:innen

Probleme mit Datentypen vermeiden

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

• Zeitstempel als Strings gespeichert: Stellen Sie sicher, dass Ihre Datumsspalten in Ihrer Quelldatenbank einen Timestamp- oder Datetime-Typ verwenden und nicht einen Varchar- oder String-Typ.
• Zahlen als Strings gespeichert: Wandeln Sie numerische Spalten in Ihrer Quellabfrage vor der Synchronisierung in Integer- oder Gleitkommazahl-Typen um.
• Inkonsistente Typen zwischen Synchronisierungen: Wenn sich ein Spaltentyp zwischen Synchronisierungen ändert, kann Braze die neuen Daten ablehnen. Überprüfen Sie, ob 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 anhand der externen ID, des Nutzer-Alias, der Braze-ID, der E-Mail-Adresse oder der Telefonnummer aktualisieren. Sie können Nutzer:innen anhand der externen ID, des Nutzer-Alias oder der Braze-ID löschen.

Was synchronisiert wird

Bei jeder Synchronisierung sucht Braze nach Zeilen, die zuvor noch nicht synchronisiert wurden. Dies wird anhand der Spalte UPDATED_AT in Ihrer Tabelle oder Ansicht geprüft. Braze wählt alle Zeilen aus und importiert sie, bei denen UPDATED_AT später als der zuletzt synchronisierte UPDATED_AT-Wert ist. Zeilen am exakten Grenz-Zeitstempel 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 beim 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. Um doppelte Synchronisierungen und unnötigen Datenpunktverbrauch 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"
}

Während der nächsten geplanten Synchronisierung synchronisiert Braze alle Zeilen mit einem UPDATED_AT-Zeitstempel, der später als der zuletzt synchronisierte Zeitstempel ist. Braze aktualisiert oder fügt Felder hinzu, sodass Sie nicht jedes Mal das vollständige Kundenprofil 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 ihr UPDATED_AT-Wert (2022-07-16 00:25:30) liegt vor dem gespeicherten Zeitstempel (2022-07-19 09:07:23), sodass sie 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 Stellen Sie sicher, dass die UPDATED_AT-Zeit nicht mit der Synchronisierungszeit übereinstimmt. 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 später als der gespeicherte Zeitstempel ist. Diese neue Zeile und die bestehende Zeile für customer_5678 (deren UPDATED_AT 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 sogar später als die Startzeit des Durchlaufs einer bestimmten Synchronisierung sein. Dies wird jedoch nicht empfohlen, da es den letzten UPDATED_AT-Zeitstempel „in die Zukunft“ verschiebt und nachfolgende Synchronisierungen frühere Werte nicht synchronisieren werden.

Verwenden Sie einen UTC-Zeitstempel für die Spalte UPDATED_AT

Die Spalte UPDATED_AT sollte in UTC angegeben werden, um Probleme mit der Sommerzeit zu vermeiden. Bevorzugen Sie nach Möglichkeit reine UTC-Funktionen, wie z. B. SYSDATE() anstelle von 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 das von CDI erwartete Format zu bringen, 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 zuvor noch nicht synchronisiert wurden. Dies wird anhand der UPDATED_AT-Spalte in Ihrer Tabelle oder Ansicht überprüft. Braze wählt alle Zeilen aus und importiert sie, bei denen UPDATED_AT nach dem zuletzt synchronisierten UPDATED_AT-Wert liegt – unabhängig davon, ob sie mit dem übereinstimmen, was aktuell im Kundenprofil gespeichert ist. Zeilen am Grenz-Timestamp können ebenfalls erneut synchronisiert werden, wenn neue Zeilen denselben Timestamp aufweisen. Daher empfehlen wir, nur Attribute zu synchronisieren, die Sie hinzufügen oder aktualisieren möchten.

Der Datenpunkt-Verbrauch ist bei CDI identisch mit anderen Aufnahmemethoden wie REST APIs oder SDKs. Stellen Sie daher sicher, dass Sie nur neue oder aktualisierte Attribute in Ihre Quelltabellen aufnehmen.

EXTERNAL_ID von der PAYLOAD-Spalte trennen

Das PAYLOAD-Objekt sollte keine externe ID oder einen anderen ID-Typ enthalten.

Ein Attribut entfernen

Sie können es auf null setzen, wenn Sie ein Attribut aus dem Profil einer Nutzerin oder eines Nutzers entfernen möchten. Wenn ein Attribut unverändert bleiben soll, senden Sie es nicht an Braze, bis es aktualisiert wurde. Um ein Attribut vollständig zu entfernen, verwenden Sie TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Inkrementelle Aktualisierungen durchführen

Führen Sie inkrementelle Aktualisierungen Ihrer Daten durch, um unbeabsichtigte Überschreibungen bei gleichzeitigen Aktualisierungen zu verhindern.

Wichtig

• Aktualisierungen verschiedener Attribute: In der großen Mehrheit der Fälle haben zwei Aktualisierungen, die nicht dieselben Attribute betreffen, völlig unabhängige Ergebnisse. Wenn Sie beispielsweise das Color-Attribut und separat das Size-Attribut aktualisieren, sollten beide Aktualisierungen korrekt angewendet werden, auch wenn sie innerhalb von Sekunden aufeinanderfolgen.
• Aktualisierungen desselben Attributs: Race-Conditions können auftreten, wenn mehrere Aktualisierungen innerhalb eines einzelnen Synchronisierungslaufs dasselbe Attribut betreffen. In diesen seltenen Fällen kann eine Aktualisierung eine andere überschreiben. Der beste Weg, dieses Verhalten zu verhindern, besteht darin sicherzustellen, dass die Quelldaten Ihrer CDI-Synchronisierung nur den aktuellsten Zustand jeder Nutzerin oder jedes Nutzers widerspiegeln oder dass alle Aktualisierungen für eine:n bestimmte:n Nutzer:in oder eine Nutzer:in-Attribut-Kombination in einer einzelnen Zeile enthalten sind.
• Objekt-Array-Operatoren: Die einzigen Ausnahmen von unabhängigen Aktualisierungen sind die Operatoren $add, $remove und $update für Objekt-Arrays, bei denen Aktualisierungen desselben Arrays sich gegenseitig beeinflussen können.
• Events: Race-Conditions betreffen keine Events, da jedes Event eindeutig ist und einen zugehörigen Timestamp hat.

Der beste Weg, dieses Verhalten zu verhindern, besteht darin sicherzustellen, dass die Quelldaten Ihrer CDI-Synchronisierung nur den aktuellsten Zustand jeder Nutzerin oder jedes Nutzers widerspiegeln oder dass alle Aktualisierungen für eine:n bestimmte:n Nutzer:in oder eine Nutzer:in-Attribut-Kombination in einer einzelnen Zeile enthalten sind.

Einen JSON-String aus einer anderen Tabelle erstellen

Wenn Sie jedes Attribut intern in einer eigenen Spalte speichern möchten, müssen Sie diese Spalten in einen JSON-String umwandeln, um die Synchronisierung mit Braze zu befüllen. Dazu können Sie eine Abfrage wie die folgende verwenden:

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

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

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,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    ) as PAYLOAD FROM "EXAMPLE_USER_DATA";

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
     attribute_2 STRING,
     attribute_3 NUMERIC,
     my_user_id STRING);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        'attribute_1' AS attribute_1,
        'attribute_2'AS attribute_2,
        'yet_another_attribute'AS attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (
    attribute_1 string,
    attribute_2 STRING,
    attribute_3 NUMERIC,
    my_user_id STRING
);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        attribute_1,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE TABLE [braze].[users] (
    attribute_1 VARCHAR,
    attribute_2 VARCHAR,
    attribute_3 VARCHAR,
    attribute_4 VARCHAR,
    user_id VARCHAR
)
GO

CREATE VIEW [braze].[user_update_example]
AS SELECT
    user_id as EXTERNAL_ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[users] ;

Den UPDATED_AT-Timestamp verwenden

Braze verwendet den UPDATED_AT-Timestamp, um nachzuverfolgen, welche Daten erfolgreich synchronisiert wurden. CDI erfasst außerdem die Anzahl der Zeilen zum zuletzt synchronisierten Timestamp. Wenn zwischen den Läufen neue Zeilen mit demselben Timestamp hinzugefügt werden, synchronisiert CDI alle Zeilen mit diesem Timestamp erneut, was zu doppelten Daten führen kann. Weitere Details und Tipps finden Sie unter Erneute Synchronisierung von Zeilen mit doppelten Timestamps 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 die Payload-Formatierung für Cloud Data Ingestion sind unter Tabelleneinrichtung für Cloud Data Ingestion dokumentiert.

Verwenden Sie diese Seite, um Folgendes zu unterscheiden:

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

Timeouts bei Data-Warehouse-Abfragen vermeiden

Wir empfehlen, Abfragen innerhalb einer Stunde abzuschließen, um eine optimale Performance zu erzielen und potenzielle Fehler zu vermeiden. Wenn Abfragen diesen Zeitrahmen überschreiten, überprüfen Sie Ihre Data-Warehouse-Konfiguration. Die Optimierung der Ihrem Warehouse zugewiesenen Ressourcen kann die Ausführungsgeschwindigkeit der Abfragen verbessern.

Produkteinschränkungen