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.

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 Zeitstempel- oder Datetime-Typ verwenden und keinen Varchar- oder String-Typ.
• Zahlen als Strings gespeichert: Konvertieren Sie numerische Spalten in Ihrer Quellabfrage vor der Synchronisierung in Integer- oder Gleitkommazahl-Typen.
• 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 von externer ID, Nutzer-Alias, Braze-ID, E-Mail oder Telefonnummer aktualisieren. Sie können Nutzer:innen anhand von externer ID, Nutzer-Alias oder Braze-ID löschen.

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

Weitere Tipps

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

Bei jeder Synchronisierung sucht Braze nach Zeilen, die zuvor nicht synchronisiert wurden. Wir überprüfen dies anhand der UPDATED_AT-Spalte in Ihrer Tabelle oder View. Braze wählt alle Zeilen aus und importiert sie, bei denen UPDATED_AT später ist als der zuletzt synchronisierte UPDATED_AT-Wert – unabhängig davon, ob sie mit dem übereinstimmen, was aktuell im Nutzerprofil gespeichert ist. Zeilen am Grenz-Zeitstempel können ebenfalls erneut synchronisiert werden, wenn neue Zeilen denselben Zeitstempel haben. Daher empfehlen wir, nur Attribute zu synchronisieren, die Sie hinzufügen oder aktualisieren möchten.

Die Datenpunkt-Nutzung ist bei CDI identisch mit anderen Aufnahmemethoden wie REST APIs oder SDKs. Es liegt daher an Ihnen sicherzustellen, 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

In einer PAYLOAD-Spalte können Sie ein Attribut auf null setzen, wenn Sie es aus dem Profil einer/eines Nutzer:in entfernen 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

Führen Sie inkrementelle Updates Ihrer Daten durch, um unbeabsichtigtes Überschreiben bei gleichzeitigen Aktualisierungen zu vermeiden.

Wichtig

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

Der beste Weg, dieses Verhalten zu verhindern, ist sicherzustellen, dass die Quelldaten Ihrer CDI-Synchronisierung nur den aktuellsten Zustand jeder/jedes Nutzer:in widerspiegeln oder dass alle Updates für eine bestimmte Nutzer:in oder eine Nutzer:in-Attribut-Kombination in einer einzelnen 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 Erstellung eines JSON-Strings zu synchronisieren, verwenden Sie stattdessen die Option Visual oder SQL. Details finden Sie unter Eine Datendefinitionsoption wählen.

Um den JSON-String zu erstellen, 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-Zeitstempel verwenden

Braze verwendet den UPDATED_AT-Zeitstempel, um zu verfolgen, welche Daten erfolgreich synchronisiert wurden. CDI verfolgt auch die Anzahl der Zeilen beim zuletzt synchronisierten Zeitstempel. Wenn zwischen den Läufen neue Zeilen mit demselben Zeitstempel hinzugefügt werden, synchronisiert CDI alle Zeilen mit diesem Zeitstempel erneut, was zu doppelten Daten führen kann. Weitere Details und Tipps finden Sie unter Erneutes Synchronisieren 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 Cloud-Data-Ingestion-Tabelleneinrichtung und die Payload-Formatierung sind unter Tabelleneinrichtung für Cloud Data Ingestion dokumentiert.

Verwenden Sie diese Seite, um zu unterscheiden zwischen:

• Quelltabellenanforderungen (erforderliche Spalten, Bezeichnerspalten 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 von Abfragen verbessern.

Produktbeschränkungen