Buenas prácticas

La ingesta de datos en la nube 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.

Evitar problemas con los tipos de datos

Cuando uses CDI para sincronizar datos desde fuentes externas (como Databricks o Snowflake), asegúrate de que las columnas de origen usen los tipos de datos correctos antes de sincronizar. Entre los problemas más comunes se incluyen:

• Marcas de tiempo almacenadas como cadenas: Asegúrate de que las columnas de fecha usen un tipo timestamp o datetime en tu base de datos de origen, no varchar ni cadena.
• Números almacenados como cadenas: Convierte las columnas numéricas a tipos entero o flotante en tu consulta de origen antes de sincronizar.
• Tipos incoherentes entre sincronizaciones: Si el tipo de una columna cambia entre sincronizaciones, Braze puede rechazar los nuevos datos. Comprueba que el esquema de origen se mantenga coherente.

Para forzar o cambiar los tipos de datos de los atributos personalizados en el panel de Braze, consulta Administrar 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 de tiempo 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 exclusivamente 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. Lo comprobamos con la columna UPDATED_AT de tu tabla o vista. Braze selecciona e importa todas las filas en las que UPDATED_AT sea posterior al último valor UPDATED_AT sincronizado, independientemente de si coinciden con lo que hay actualmente en el perfil de usuario. Las filas con la marca de tiempo límite también pueden volver a sincronizarse si hay filas nuevas que comparten esa marca de tiempo. Por eso, te recomendamos sincronizar solo los atributos que quieras añadir o actualizar.

El uso de puntos de datos es idéntico con CDI que con otros métodos de ingesta, como las REST API o los SDK, así que te corresponde asegurarte de que solo añades atributos nuevos o actualizados a 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 en null si quieres 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 un atributo por completo, usa TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Haz actualizaciones incrementales

Haz actualizaciones incrementales de tus datos para evitar sobrescrituras involuntarias cuando se realizan actualizaciones simultáneas.

Importante

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

La mejor forma de evitar este comportamiento es asegurarte de que los datos de origen de tu sincronización de CDI reflejen solo el estado más reciente de cada usuario, o de que todas las actualizaciones de un usuario determinado o de un 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 internamente cada atributo en su propia columna, convierte esas columnas en una cadena JSON para rellenar PAYLOAD. Para sincronizar columnas separadas sin crear una cadena JSON, usa en su lugar la opción Visual o SQL. Para más detalles, consulta Elegir una opción de definición de datos.

Cada página de origen incluye un ejemplo práctico en el dialecto SQL de ese almacén de datos:

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

Por ejemplo, en 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";

Usa la marca de tiempo UPDATED_AT

Braze usa la marca de tiempo UPDATED_AT para hacer un seguimiento de los datos que se han sincronizado correctamente. CDI también registra el número de filas con la última marca de tiempo sincronizada. Si se añaden filas nuevas con esa misma marca de tiempo entre ejecuciones, CDI vuelve a sincronizar todas las filas con esa marca de tiempo, lo que puede provocar datos duplicados. Para más detalles y consejos, consulta Evitar volver a sincronizar filas con marcas de tiempo duplicadas.

Configuración de la tabla

Tenemos un repositorio público de GitHub para que los clientes compartan buenas prácticas o fragmentos de código. Para aportar tus propios fragmentos, ¡crea una solicitud de incorporación de cambios (pull request)!

Formato de los datos

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

Usa esa página para distinguir entre:

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

Evita tiempos de espera agotados en las consultas al almacén de datos

Te recomendamos que las consultas se completen en menos de una hora para obtener un rendimiento óptimo y evitar posibles errores. Si las consultas superan este plazo, plantéate 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