ベストプラクティス

Brazeクラウドデータ取り込みを使用すると、データウェアハウスやファイルストレージシステムからBrazeへの直接接続を設定して、関連するユーザーデータやカタログデータを同期できます。このデータをBrazeに同期すると、パーソナライゼーション、トリガー、セグメンテーションなどのユースケースに活用できます。

UPDATED_ATによる変更の追跡

注

UPDATED_ATはデータウェアハウス連携にのみ関連するものであり、ファイルストレージ同期には適用されません。

同期が実行されると、Brazeはデータウェアハウスインスタンスに直接接続し、各行のUPDATED_ATタイムスタンプを使用して変更を追跡します。UPDATED_ATは、すべてのデータウェアハウス同期で必須のフィールドです。

重要

CDIは、行の内容がBrazeの現在のデータと同じかどうかに関係なく、UPDATED_ATの値に基づいて厳密に変更を追跡します。不要なデータポイント使用量を避けるために、UPDATED_ATを使用して新規または更新されたデータのみを同期することをBrazeでは推奨しています。

例：定期同期の動作

CDI同期でUPDATED_ATがどのように使用されるかを説明するために、ユーザー属性を更新する定期同期の例を見てみましょう。

同期が実行されるたびに、CDIはまだ同期されていない行を検索します。CDIはテーブルまたはビューのUPDATED_AT列を使用してこれを確認します。Brazeは、UPDATED_ATが最後に同期されたUPDATED_ATの値よりも新しいすべての行を選択してインポートします。境界のタイムスタンプと完全に一致する行も、同じタイムスタンプの新しい行が実行間で追加された場合に再同期される可能性があります。

重要

CDIは、最後に同期されたUPDATED_ATの値における行数を追跡します。同じタイムスタンプの新しい行が実行間で追加された場合、CDIは包括的な境界（>=）に切り替え、そのタイムスタンプのすべての行（すでに処理済みのものを含む）を再同期します。重複同期や不要なデータポイント消費を避けるために、同期実行間で一意のUPDATED_AT値を使用してください。詳細については、重複タイムスタンプによる行の再同期を回避するを参照してください。

データウェアハウスで、以下のユーザーと属性をテーブルに追加し、UPDATED_ATの時刻をデータを追加した時刻に設定します。

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

次のスケジュールされた同期では、Brazeは最後に同期されたタイムスタンプよりも新しいUPDATED_ATタイムスタンプを持つすべての行を同期します。Brazeはフィールドを更新または追加するため、毎回完全なユーザープロファイルを同期する必要はありません。同期後、ユーザープロファイルには新しい更新が反映されます。

定期同期、2回目の実行：2022年7月20日 12:00 PM

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

customer_9012の新しい行が追加されましたが、そのUPDATED_ATの値（2022-07-16 00:25:30）は保存されたタイムスタンプ（2022-07-19 09:07:23）よりも前のため、同期されません。ただし、customer_5678の既存の行はUPDATED_ATの値が保存されたタイムスタンプと等しいため、包括的な境界により再同期されます。この動作の詳細については、重複タイムスタンプによる行の再同期を回避するを参照してください。保存されたUPDATED_ATは2022-07-19 09:07:23のままです。

定期同期、3回目の実行：2022年7月21日 12:00 PM

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

この3回目の実行では、customer_1234の新しい行が追加され、そのUPDATED_ATの値（2022-07-21 08:30:00）は保存されたタイムスタンプよりも新しいものです。この新しい行と、customer_5678の既存の行（UPDATED_ATが保存されたタイムスタンプと等しい）の両方が同期されます。保存されたUPDATED_ATは2022-07-21 08:30:00に更新されます。

注

UPDATED_ATの値は、特定の同期の実行開始時刻よりも未来の値を設定することも可能です。ただし、これは推奨されません。最後のUPDATED_ATタイムスタンプが「未来」に押し出され、それ以降の同期ではそれよりも前の値が同期されなくなるためです。

データ型の問題を防ぐ

CDIを使用して外部ソース（DatabricksやSnowflakeなど）からデータを同期する場合は、同期前にソース列で正しいデータ型が使用されていることを確認してください。よくある問題には以下があります。

• 文字列として保存されたタイムスタンプ: 日付列がソースデータベースでvarcharや文字列型ではなく、タイムスタンプ型またはdatetime型を使用していることを確認してください。
• 文字列として保存された数値: 同期前に、ソースクエリで数値列を整数型または浮動小数点型にキャストしてください。
• 同期間で一貫しない型: 同期間で列の型が変更されると、Brazeは新しいデータを拒否する場合があります。ソーススキーマが一貫していることを確認してください。

Brazeダッシュボードでカスタム属性のデータ型を強制または変更する方法については、カスタムデータの管理を参照してください。

external ID、ユーザーエイリアス、Braze ID、メール、または電話番号でユーザーデータを更新できます。external ID、ユーザーエイリアス、またはBraze IDでユーザーを削除できます。

UPDATED_AT列にUTCタイムスタンプを使用する

UPDATED_AT列は、夏時間に関する問題を防ぐためにUTCで設定する必要があります。可能な限り、CURRENT_DATE()ではなくSYSDATE()などのUTC専用の関数を使用してください。

重複タイムスタンプによる行の再同期を避ける

CDIは、最後に同期されたUPDATED_ATタイムスタンプにおける行数を追跡します。CDIが前回の実行以降に同じタイムスタンプで新しい行が追加されたことを検出すると、包含境界（>=）を使用してそのタイムスタンプのすべての行（すでに処理済みのものを含む）を再選択します。それ以外の場合、CDIは排他境界（>）を使用し、最後に同期された値よりも厳密に後の行のみを選択します。

例えば、同期がUPDATED_AT = 2025-04-01 00:00:00の5行を処理し、後から同じタイムスタンプで6行目が追加された場合、次の同期はカウントの変化を検出し、6行すべてを再同期します。これにより、重複データや不要なデータポイント消費が発生する可能性があります。

これを避けるには：

• VIEWに対して同期を設定する場合、デフォルト値としてCURRENT_TIMESTAMPを使用しないでください。UPDATED_ATフィールドがクエリの実行時刻に評価されるため、同期が実行されるたびにすべてのデータが同期されてしまいます。
• 長時間実行されるパイプラインやクエリがソーステーブルにデータを書き込んでいる場合、同期と同時に実行することを避けるか、挿入される各行に同じタイムスタンプを使用することを避けてください。
• トランザクションを使用して、同じタイムスタンプを共有するすべての行を書き込みます。
• ユニークで単調増加するUPDATED_ATの値を使用して、処理済みの行が再選択されることを防ぎます。

例：後続の更新を管理する

この例では、最初にデータを同期し、その後の更新では変更されたデータ（差分）のみを更新する一般的なプロセスを示します。ユーザーデータを含むテーブルEXAMPLE_DATAがあるとします。1日目のテーブルには次の値があります：

このデータをPAYLOAD列に変換するには、次のクエリを実行します：

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;

このデータはまだBrazeに同期されていないため、CDIのソーステーブルにすべて追加します：

同期が実行され、Brazeは「2023-03-16 15:00:00」までの利用可能なすべてのデータを同期したことを記録します。次に、2日目の朝にETLが実行され、ユーザーテーブルの一部のフィールドが更新されます（*で示されています）：

ここで、変更された値のみをCDIソーステーブルに追加する必要があります。古い行を更新するのではなく、これらの行を追加（アペンド）できます。そのテーブルは次のようになります：

CDIは新しい行のみを同期するため、次に実行される同期では最後の5行のみが同期されます。

その他のヒント

消費を最小限に抑えるために新規または更新された属性のみを書き込む

同期が実行されるたびに、Brazeは以前に同期されていない行を検索します。テーブルまたはビューのUPDATED_AT列を使用してこの確認を行います。Brazeは、UPDATED_ATが最後に同期されたUPDATED_AT値よりも後の行をすべて選択してインポートします。これは、現在ユーザープロファイルに存在するものと同じかどうかに関係なく行われます。境界タイムスタンプの行は、新しい行が同じタイムスタンプを共有する場合に再同期される場合もあります。このことから、追加または更新したい属性のみを同期することをお勧めします。

CDIを使用した場合のデータポイント使用量は、REST APIやSDKなどの他の取り込み方法と同じです。そのため、ソーステーブルに新規または更新された属性のみを追加するようにしてください。

EXTERNAL_IDをPAYLOAD列から分離する

PAYLOADオブジェクトにexternal IDやその他のIDタイプを含めないでください。

属性を削除する

PAYLOAD列で、ユーザーのプロファイルから属性を省略したい場合はnullに設定できます。属性を変更せずに保持したい場合は、更新されるまでBrazeに送信しないでください。属性を完全に削除するには、TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...))を使用します。

増分更新を行う

同時更新が行われた際に意図しない上書きを防ぐために、データの増分更新を行ってください。

重要

• 異なる属性への更新： ほとんどの場合、2つの更新が同じユーザーの同じ属性に影響しなければ、完全に独立した結果になります。たとえば、あるユーザーのColor属性を更新し、別途Size属性を更新した場合、互いに数秒以内に発生しても、両方の更新が正しく適用されます。
• 同じ属性への更新： 単一の同期実行内で複数の更新が同じ属性を対象とする場合、競合が発生することがあります。このまれなケースでは、1つの更新が別の更新を上書きする可能性があります。この動作を防ぐ最善の方法は、CDI同期のソースデータが各ユーザーの最新の状態のみを反映するようにするか、特定のユーザーまたはユーザー＋属性の組み合わせに対するすべての更新を単一の行に含めることです。
• オブジェクト配列演算子： 独立した更新の唯一の例外は、オブジェクト配列の$add、$remove、$update演算子であり、同じ配列への更新が互いに干渉する場合があります。
• イベント： 各イベントは一意であり、タイムスタンプが関連付けられているため、競合はイベントに影響しません。

この動作を防ぐ最善の方法は、CDI同期のソースデータが各ユーザーの最新の状態のみを反映するようにするか、特定のユーザーまたはユーザー＋属性の組み合わせに対するすべての更新を単一の行に含めることです。

別のテーブルからJSON文字列を作成する

PAYLOAD列を使用し、各属性を内部的にそれぞれの列に格納している場合は、それらの列をJSON文字列に変換してPAYLOADに格納します。JSON文字列を構築せずに個別の列を同期するには、代わりにVisualまたはSQLオプションを使用してください。詳細については、データ定義オプションの選択を参照してください。

JSON文字列を構築するには、次のようなクエリを使用できます。

• 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] ;

UPDATED_ATタイムスタンプを使用する

BrazeはUPDATED_ATタイムスタンプを使用して、正常に同期されたデータを追跡します。CDIは、最後に同期されたタイムスタンプの行数も追跡します。同じタイムスタンプで新しい行が実行間に追加された場合、CDIはそのタイムスタンプのすべての行を再同期するため、データが重複する可能性があります。詳細とヒントについては、重複タイムスタンプの行の再同期を避けるを参照してください。

テーブル構成

ベストプラクティスやコードスニペットを共有するための公開GitHubリポジトリがあります。独自のスニペットを寄稿するには、プルリクエストを作成してください。

データフォーマット

Cloud Data Ingestionのテーブル設定要件とペイロードフォーマット要件は、Cloud Data Ingestionのテーブル設定に記載されています。

このページを使用して、以下を区別してください。

• ソーステーブルの要件（必須列、識別子列、UPDATED_ATの動作）
• ペイロードの要件（各データタイプの/users/trackオブジェクトフォーマットに一致する必要があるフィールド）

データウェアハウスクエリのタイムアウトを回避する

最適なパフォーマンスと潜在的なエラーの回避のために、クエリは1時間以内に完了することをお勧めします。クエリがこの時間枠を超える場合は、データウェアハウスの構成を見直すことを検討してください。ウェアハウスに割り当てるリソースを最適化することで、クエリの実行速度を向上させることができます。

製品の制限事項