Buenas prácticas

La ingesta de datos de Cloud de Braze te permite configurar una conexión directa desde tu almacén de datos o sistema de almacenamiento de archivos a Braze para sincronizar datos relevantes de usuarios o catálogos. Al sincronizar estos datos con Braze, puedes aprovecharlos para casos de uso como la personalización, el desencadenamiento o la segmentación.

Rastrea los cambios con UPDATED_AT

Nota

UPDATED_AT es relevante únicamente para integraciones de almacén de datos, no para sincronizaciones de almacenamiento de archivos.

Cuando se ejecuta una sincronización, Braze se conecta directamente a tu instancia de almacén de datos y usa la marca de tiempo UPDATED_AT de cada fila para el seguimiento de cambios. UPDATED_AT es un campo obligatorio para todas las sincronizaciones de almacén de datos.

Importante

CDI rastrea los cambios estrictamente en función de los valores de UPDATED_AT, independientemente de si el contenido de la fila es el mismo que el que existe actualmente en Braze. Braze recomienda usar UPDATED_AT para sincronizar solo datos nuevos o actualizados, lo que evita un uso innecesario de puntos de datos.

Ejemplo: comportamiento de sincronización recurrente

Para ilustrar cómo se usa UPDATED_AT en una sincronización CDI, consulta este ejemplo de sincronización recurrente para actualizar atributos de usuario.

Cada vez que se ejecuta una sincronización, CDI busca filas que no se hayan sincronizado previamente. CDI lo verifica usando la columna UPDATED_AT en tu tabla o vista. Braze selecciona e importa todas las filas donde UPDATED_AT es posterior al último valor de UPDATED_AT sincronizado. Las filas en la marca de tiempo límite exacta también pueden volver a sincronizarse si se agregan nuevas filas con esa misma marca de tiempo entre ejecuciones.

Importante

CDI rastrea el número de filas con el último valor de UPDATED_AT sincronizado. Si se agregan nuevas filas con esa misma marca de tiempo entre ejecuciones, CDI cambia a un límite inclusivo (>=) y vuelve a sincronizar todas las filas con esa marca de tiempo, incluidas las que ya fueron procesadas. Para evitar sincronizaciones duplicadas y consumo innecesario de puntos de datos, usa valores de UPDATED_AT únicos entre ejecuciones de sincronización. Para más información, consulta Evitar la resincronización de filas con marcas de tiempo duplicadas.

En tu almacén de datos, agrega los siguientes usuarios y atributos a tu tabla, configurando la hora de UPDATED_AT con el momento en que agregas estos datos:

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

Durante la siguiente sincronización programada, Braze sincroniza todas las filas con una marca de tiempo UPDATED_AT posterior a la marca de tiempo sincronizada más reciente. Braze actualiza o agrega campos, por lo que no necesitas sincronizar el perfil de usuario completo cada vez. Después de la sincronización, los perfiles de usuario reflejan las nuevas actualizaciones:

Sincronización recurrente, segunda ejecución el 20 de julio de 2022 a las 12 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"
}

Se agregó una nueva fila para customer_9012, pero su valor de UPDATED_AT (2022-07-16 00:25:30) es anterior a la marca de tiempo almacenada (2022-07-19 09:07:23), por lo que no se sincronizará. Sin embargo, la fila existente para customer_5678 tiene un valor de UPDATED_AT igual a la marca de tiempo almacenada, por lo que se vuelve a sincronizar debido al límite inclusivo. Para más detalles sobre este comportamiento, consulta Evitar la resincronización de filas con marcas de tiempo duplicadas. La marca de tiempo almacenada de UPDATED_AT permanece en 2022-07-19 09:07:23.

Sincronización recurrente, tercera ejecución el 21 de julio de 2022 a las 12 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"
}

En esta tercera ejecución, se agregó otra fila nueva para customer_1234 con un valor de UPDATED_AT (2022-07-21 08:30:00) posterior a la marca de tiempo almacenada. Esta nueva fila y la fila existente para customer_5678 (que tiene un UPDATED_AT igual a la marca de tiempo almacenada) se sincronizan ambas. La marca de tiempo almacenada de UPDATED_AT se establece ahora como 2022-07-21 08:30:00.

Nota

Se permite que los valores de UPDATED_AT sean incluso posteriores a la hora de inicio de ejecución de una sincronización determinada. Sin embargo, esto no se recomienda, ya que empuja la última marca de tiempo de UPDATED_AT “hacia el futuro” y las sincronizaciones posteriores no sincronizarán valores anteriores.

Prevenir problemas de tipos de datos

Al usar CDI para sincronizar datos de fuentes externas (como Databricks o Snowflake), asegúrate de que las columnas de origen utilicen los tipos de datos correctos antes de sincronizar. Los problemas más comunes incluyen:

• Marcas de tiempo almacenadas como cadenas: Asegúrate de que las columnas de fecha utilicen un tipo timestamp o datetime en tu base de datos de origen, no un varchar o string.
• Números almacenados como cadenas: Convierte las columnas numéricas a tipos integer o float en tu consulta de origen antes de sincronizar.
• Tipos inconsistentes entre sincronizaciones: Si el tipo de una columna cambia entre sincronizaciones, Braze puede rechazar los nuevos datos. Verifica que el esquema de origen se mantenga consistente.

Para forzar o cambiar los tipos de datos de los atributos personalizados en el panel de Braze, consulta Gestionar datos personalizados.

Puedes actualizar los datos de usuario por ID externo, alias de usuario, ID de Braze, correo electrónico o número de teléfono. Puedes eliminar usuarios por ID externo, alias de usuario o ID de Braze.

Usa una marca temporal UTC para la columna UPDATED_AT

La columna UPDATED_AT debe estar en UTC para evitar problemas con el horario de verano. Siempre que sea posible, usa funciones exclusivas de UTC, como SYSDATE() en lugar de CURRENT_DATE().

Evitar la resincronización de filas con marcas de tiempo duplicadas

CDI registra el número de filas en la última marca de tiempo de UPDATED_AT sincronizada. Si CDI detecta que se han añadido nuevas filas con esa misma marca de tiempo desde la última ejecución, utiliza un límite inclusivo (>=) para volver a seleccionar todas las filas con esa marca de tiempo, incluidas las ya procesadas. De lo contrario, CDI utiliza un límite exclusivo (>) y solo selecciona filas estrictamente posteriores al último valor sincronizado.

Por ejemplo, si una sincronización procesa cinco filas con UPDATED_AT = 2025-04-01 00:00:00, y posteriormente se añade una sexta fila con la misma marca de tiempo, la siguiente sincronización detecta el cambio en el recuento y vuelve a sincronizar las seis filas. Esto puede resultar en datos duplicados y consumo innecesario de puntos de datos.

Para evitar esto:

• Si estás configurando una sincronización contra un VIEW, no utilices CURRENT_TIMESTAMP como valor predeterminado. Esto hace que todos los datos se sincronicen cada vez que se ejecuta la sincronización, porque el campo UPDATED_AT se evalúa a la hora en que se ejecuta la consulta.
• Si tienes pipelines o consultas de larga duración que escriben datos en tu tabla de origen, evita ejecutarlos simultáneamente con una sincronización, o evita utilizar la misma marca de tiempo para cada fila insertada.
• Utiliza una transacción para escribir todas las filas que compartan la misma marca de tiempo.
• Utiliza valores de UPDATED_AT únicos y monótonamente crecientes para evitar que las filas se vuelvan a seleccionar después de haber sido procesadas.

Ejemplo: administración de actualizaciones posteriores

Este ejemplo muestra el proceso general para sincronizar datos por primera vez y luego solo actualizar los datos cambiantes (deltas) en las actualizaciones posteriores. Supongamos que tenemos una tabla EXAMPLE_DATA con algunos datos de usuario. El día 1 tiene los siguientes valores:

Para obtener estos datos en una columna PAYLOAD, puedes ejecutar la siguiente consulta:

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;

Nada de esto se ha sincronizado antes con Braze, así que añádelo todo a la tabla de origen para CDI:

Se ejecuta una sincronización y Braze registra que has sincronizado todos los datos disponibles hasta “2023-03-16 15:00:00”. A continuación, en la mañana del día 2, se ejecuta un ETL y se actualizan algunos campos de la tabla de usuarios (marcados con *):

Ahora solo necesitas añadir los valores modificados a la tabla de origen de CDI. Estas filas pueden añadirse en lugar de actualizar las filas antiguas. Esa tabla ahora tiene este aspecto:

CDI solo sincronizará las nuevas filas, por lo que la próxima sincronización que se ejecute solo sincronizará las últimas cinco filas.

Consejos adicionales

Escribe solo atributos nuevos o actualizados para minimizar el consumo

Cada vez que se ejecuta una sincronización, Braze busca filas que no se hayan sincronizado previamente. Verificamos esto usando la columna UPDATED_AT en tu tabla o vista. Braze selecciona e importa cualquier fila donde UPDATED_AT sea posterior al último valor UPDATED_AT sincronizado, independientemente de si son iguales a lo que hay actualmente en el perfil de usuario. Las filas en la marca temporal límite también pueden volver a sincronizarse si nuevas filas comparten esa marca temporal. Teniendo esto en cuenta, recomendamos sincronizar solo los atributos que desees agregar o actualizar.

El uso de puntos de datos es idéntico al usar CDI que con otros métodos de ingesta como REST API o SDK, por lo que depende de ti asegurarte de que solo estés agregando atributos nuevos o actualizados en tus tablas de origen.

Separa EXTERNAL_ID de la columna PAYLOAD

El objeto PAYLOAD no debe incluir un ID externo ni otro tipo de ID.

Eliminar un atributo

En una columna PAYLOAD, puedes establecer un atributo como null si deseas omitirlo del perfil de un usuario. Si quieres que un atributo permanezca sin cambios, no lo envíes a Braze hasta que se haya actualizado. Para eliminar completamente un atributo, usa TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Realiza actualizaciones incrementales

Realiza actualizaciones incrementales a tus datos para prevenir sobrescrituras involuntarias cuando se realizan actualizaciones simultáneas.

Importante

• Actualizaciones a atributos diferentes: En la gran mayoría de los casos, si dos actualizaciones no afectan a los mismos atributos de un usuario, tienen resultados completamente independientes. Por ejemplo, si actualizas el atributo Color de un usuario y por separado actualizas su atributo Size, ambas actualizaciones deberían aplicarse correctamente, incluso si ocurren con segundos de diferencia.
• Actualizaciones al mismo atributo: Las condiciones de carrera pueden ocurrir cuando múltiples actualizaciones apuntan al mismo atributo dentro de una sola ejecución de sincronización. En estos casos poco frecuentes, una actualización puede sobrescribir a otra. La mejor forma de prevenir este comportamiento es asegurar que los datos de origen de tu sincronización CDI reflejen solo el estado más reciente de cada usuario, o que todas las actualizaciones para un usuario dado o par usuario+atributo estén contenidas en una sola fila.
• Operadores de matrices de objetos: Las únicas excepciones a las actualizaciones independientes son con los operadores $add, $remove y $update para matrices de objetos, donde las actualizaciones a la misma matriz pueden interactuar entre sí.
• Eventos: Las condiciones de carrera no afectan a los eventos porque cada evento es único y tiene una marca temporal asociada.

La mejor forma de prevenir este comportamiento es asegurar que los datos de origen de tu sincronización CDI reflejen solo el estado más reciente de cada usuario, o que todas las actualizaciones para un usuario dado o par usuario+atributo estén contenidas en una sola fila.

Crea una cadena JSON a partir de otra tabla

Si usas una columna PAYLOAD y almacenas cada atributo en su propia columna internamente, convierte esas columnas a una cadena JSON para completar PAYLOAD. Para sincronizar columnas separadas sin construir una cadena JSON, usa la opción Visual o SQL en su lugar. Para más detalles, consulta Elige una opción de definición de datos.

Para construir la cadena JSON, puedes usar una consulta como:

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

Usa la marca temporal UPDATED_AT

Braze usa la marca temporal UPDATED_AT para rastrear qué datos se han sincronizado correctamente. CDI también rastrea el número de filas en la última marca temporal sincronizada. Si se agregan nuevas filas con esa misma marca temporal entre ejecuciones, CDI vuelve a sincronizar todas las filas con esa marca temporal, lo que puede generar datos duplicados. Para más detalles y consejos, consulta Evitar resincronizar filas con marcas temporales duplicadas.

Configuración de tablas

Tenemos un repositorio público en GitHub para que los clientes compartan buenas prácticas o fragmentos de código. Para contribuir con tus propios fragmentos, ¡crea un pull request!

Formato de datos

Los requisitos de configuración de tablas y de formato de carga útil de Cloud Data Ingestion están documentados en Configuración de tablas para Cloud Data Ingestion.

Usa esa página para distinguir:

• Requisitos de tablas de origen (columnas obligatorias, columnas de identificador y comportamiento de UPDATED_AT)
• Requisitos de carga útil (qué campos deben coincidir con el formato del objeto /users/track para cada tipo de datos)

Evitar tiempos de espera en consultas del almacén de datos

Recomendamos que las consultas se completen en un máximo de una hora para un rendimiento óptimo y evitar posibles errores. Si las consultas superan este periodo, considera revisar la configuración de tu almacén de datos. Optimizar los recursos asignados a tu almacén puede ayudar a mejorar la velocidad de ejecución de las consultas.

Limitaciones del producto