Melhores práticas

A Ingestão de Dados na Nuvem da Braze permite que você configure uma conexão direta do seu data warehouse ou sistema de armazenamento de arquivos para a Braze, sincronizando dados relevantes de usuários ou catálogos. Quando você sincroniza esses dados com a Braze, pode aproveitá-los para casos de uso como personalização, acionamento ou segmentação.

Entendendo a coluna UPDATED_AT

Nota

UPDATED_AT é relevante apenas para integrações de data warehouse, não para sincronizações S3.

Quando uma sincronização é executada, a Braze se conecta diretamente à sua instância de data warehouse, recupera todos os novos dados da tabela especificada e atualiza os dados correspondentes no seu dashboard da Braze. Cada vez que a sincronização é executada, a Braze reflete quaisquer dados atualizados.

Importante

A CDI da Braze sincroniza linhas estritamente com base no valor de UPDATED_AT, independentemente de o conteúdo da linha ser o mesmo do que está atualmente na Braze. Dado isso, recomendamos usar UPDATED_AT corretamente para sincronizar apenas dados novos ou atualizados, a fim de evitar o uso desnecessário de pontos de dados.

Exemplo: sincronização recorrente

Para ilustrar como UPDATED_AT é usado em uma sincronização CDI, considere este exemplo de sincronização recorrente para atualizar atributos de usuários:

• Fontes de armazenamento de arquivos
  • Amazon S3

Tipos de dados suportados

A Ingestão de Dados na Nuvem suporta os seguintes tipos de dados:

• Atributos de usuário, incluindo:
  • Atributos personalizados aninhados
  • Arrays de objetos
  • Status de inscrições
• Eventos personalizados
• Eventos de compra
• Itens do catálogo
• Solicitações de exclusão de usuário

Evitando problemas com tipos de dados

Ao usar a CDI para sincronizar dados de fontes externas (como Databricks ou Snowflake), certifique-se de que as colunas de origem usem os tipos de dados corretos antes da sincronização. Problemas comuns incluem:

• Timestamps armazenados como strings: certifique-se de que suas colunas de data usem um tipo timestamp ou datetime no banco de dados de origem, não varchar ou string.
• Números armazenados como strings: converta colunas numéricas para tipos integer ou float na sua consulta de origem antes da sincronização.
• Tipos inconsistentes entre sincronizações: se o tipo de uma coluna mudar entre sincronizações, a Braze pode rejeitar os novos dados. Verifique se o esquema de origem permanece consistente.

Para forçar ou alterar tipos de dados de atributos personalizados no dashboard da Braze, consulte Gerenciar dados personalizados.

Você pode atualizar dados de usuários por ID externo, alias de usuário, ID Braze, e-mail ou número de telefone. Você pode excluir usuários por ID externo, alias de usuário ou ID Braze.

O que é sincronizado

Cada vez que uma sincronização é executada, a Braze procura linhas que não foram sincronizadas anteriormente. Verificamos isso usando a coluna UPDATED_AT na sua tabela ou visualização. A Braze seleciona e importa quaisquer linhas onde UPDATED_AT é posterior ao último valor UPDATED_AT sincronizado. Linhas no timestamp exato do limite também podem ser re-sincronizadas se novas linhas forem adicionadas com o mesmo timestamp entre as execuções.

Importante

A CDI rastreia o número de linhas no último valor UPDATED_AT sincronizado. Se novas linhas forem adicionadas com o mesmo timestamp entre as execuções, a CDI muda para um limite inclusivo (>=) e re-sincroniza todas as linhas naquele timestamp, incluindo as já processadas. Para evitar sincronizações duplicadas e consumo desnecessário de pontos de dados, use valores UPDATED_AT únicos entre as execuções de sincronização. Para saber mais, consulte Evitar re-sincronização de linhas com timestamps duplicados.

No seu data warehouse, adicione os seguintes usuários e atributos à sua tabela, definindo o horário UPDATED_AT para o momento em que você adicionar esses dados:

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 a próxima sincronização programada, a Braze sincroniza todas as linhas com um timestamp UPDATED_AT posterior ao timestamp mais recente sincronizado. A Braze atualiza ou adiciona campos, então você não precisa sincronizar o perfil completo do usuário a cada vez. Após a sincronização, os perfis de usuários refletem as novas atualizações:

Sincronização recorrente, segunda execução em 20 de julho de 2022 às 12h

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

Uma nova linha foi adicionada para customer_9012, mas seu valor UPDATED_AT (2022-07-16 00:25:30) é anterior ao timestamp armazenado (2022-07-19 09:07:23), então ela não será sincronizada. No entanto, a linha existente para customer_5678 tem um valor UPDATED_AT igual ao timestamp armazenado, então ela é re-sincronizada devido ao limite inclusivo. Para mais detalhes sobre esse comportamento, consulte Certifique-se de que o horário UPDATED_AT não seja o mesmo que o da sua sincronização. O UPDATED_AT armazenado permanece como 2022-07-19 09:07:23.

Sincronização recorrente, terceira execução em 21 de julho de 2022 às 12h

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

Nesta terceira execução, outra nova linha foi adicionada para customer_1234 com um valor UPDATED_AT (2022-07-21 08:30:00) posterior ao timestamp armazenado. Essa nova linha e a linha existente para customer_5678 (que tem um UPDATED_AT igual ao timestamp armazenado) são ambas sincronizadas. O UPDATED_AT armazenado agora está definido como 2022-07-21 08:30:00.

Nota

Valores UPDATED_AT podem ser ainda mais tardios do que o horário de início da execução de uma determinada sincronização. No entanto, isso não é recomendado, pois empurra o último timestamp UPDATED_AT “para o futuro” e sincronizações subsequentes não sincronizarão valores anteriores.

Use um timestamp UTC para a coluna UPDATED_AT

A coluna UPDATED_AT deve estar em UTC para evitar problemas com o horário de verão. Prefira funções apenas UTC, como SYSDATE() em vez de CURRENT_DATE() sempre que possível.

Evitar re-sincronização de linhas com timestamps duplicados

A CDI rastreia o número de linhas no último timestamp UPDATED_AT sincronizado. Se a CDI detectar que novas linhas foram adicionadas com o mesmo timestamp desde a última execução, ela usa um limite inclusivo (>=) para re-selecionar todas as linhas naquele timestamp, incluindo as já processadas. Caso contrário, a CDI usa um limite exclusivo (>) e seleciona apenas linhas estritamente posteriores ao último valor sincronizado.

Por exemplo, se uma sincronização processa cinco linhas com UPDATED_AT = 2025-04-01 00:00:00, e uma sexta linha é adicionada posteriormente com o mesmo timestamp, a próxima sincronização detecta a mudança na contagem e re-sincroniza todas as seis linhas. Isso pode resultar em dados duplicados e consumo desnecessário de pontos de dados.

Para evitar isso:

• Se você estiver configurando uma sincronização contra uma VIEW, não use CURRENT_TIMESTAMP como o valor padrão. Isso faz com que todos os dados sejam sincronizados toda vez que a sincronização for executada, porque o campo UPDATED_AT é avaliado no momento em que a consulta é executada.
• Se você tiver pipelines ou consultas de longa duração gravando dados na sua tabela de origem, evite executá-los simultaneamente com uma sincronização ou evite usar o mesmo timestamp para cada linha inserida.
• Use uma transação para gravar todas as linhas que compartilham o mesmo timestamp.
• Use valores UPDATED_AT únicos e monotonicamente crescentes para evitar que linhas sejam re-selecionadas após terem sido processadas.

Exemplo: gerenciando atualizações subsequentes

Esse exemplo mostra o processo geral para sincronizar dados pela primeira vez e depois atualizar apenas os dados que mudam (deltas) nas atualizações subsequentes. Digamos que temos uma tabela EXAMPLE_DATA com alguns dados de usuários. No dia 1, ela tem os seguintes valores:

Para obter esses dados no formato que a CDI espera, você pode executar a seguinte 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 disso foi sincronizado com a Braze antes, então adicione tudo à tabela de origem para CDI:

Uma sincronização é executada, e a Braze registra que você sincronizou todos os dados disponíveis até “2023-03-16 15:00:00”. Então, na manhã do dia 2, você tem um ETL que é executado e alguns campos na sua tabela de usuários são atualizados (destacados):

Agora você precisa adicionar apenas os valores alterados na tabela de origem CDI. Essas linhas podem ser anexadas em vez de atualizar as linhas antigas. Essa tabela agora fica assim:

A CDI sincronizará apenas as novas linhas, então a próxima sincronização que ocorrer sincronizará apenas as últimas cinco linhas.

Dicas adicionais

Escreva apenas atributos novos ou atualizados para minimizar o consumo

Cada vez que uma sincronização é executada, a Braze procura linhas que não foram sincronizadas anteriormente. Verificamos isso usando a coluna UPDATED_AT na sua tabela ou visualização. A Braze seleciona e importa quaisquer linhas onde UPDATED_AT é posterior ao último valor UPDATED_AT sincronizado, independentemente de serem iguais ao que está atualmente no perfil do usuário. Linhas no timestamp do limite também podem ser re-sincronizadas se novas linhas compartilharem aquele timestamp. Dado isso, recomendamos sincronizar apenas os atributos que você deseja adicionar ou atualizar.

O uso de pontos de dados é idêntico usando CDI em comparação com outros métodos de ingestão, como REST APIs ou SDKs, portanto, cabe a você garantir que está apenas adicionando atributos novos ou atualizados nas suas tabelas de origem.

Separe a coluna EXTERNAL_ID da coluna PAYLOAD

O objeto PAYLOAD não deve incluir um ID externo ou outro tipo de ID.

Remover um atributo

É possível defini-lo como null se quiser omitir um atributo do perfil de um usuário. Se você deseja que um atributo permaneça inalterado, não o envie para a Braze até que ele tenha sido atualizado. Para remover completamente um atributo, use TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Faça atualizações incrementais

Faça atualizações incrementais nos seus dados para evitar substituições não intencionais quando atualizações simultâneas forem feitas.

Importante

• Atualizações para diferentes atributos: na grande maioria dos casos, se duas atualizações não impactam os mesmos atributos de um usuário, elas têm resultados totalmente independentes. Por exemplo, se você atualizar o atributo Color de um usuário e atualizar separadamente seu atributo Size, ambas as atualizações devem ser aplicadas corretamente, mesmo que ocorram dentro de segundos uma da outra.
• Atualizações para o mesmo atributo: condições de corrida podem ocorrer quando várias atualizações visam o mesmo atributo dentro de uma única execução de sincronização. Nesses casos raros, uma atualização pode sobrescrever outra. A melhor maneira de evitar esse comportamento é garantir que os dados de origem da sua sincronização CDI reflitam apenas o estado mais recente de cada usuário, ou que todas as atualizações para um determinado usuário ou par usuário+atributo estejam contidas em uma única linha.
• Operadores de vetor de objeto: as únicas exceções para atualizações independentes são com os operadores $add, $remove e $update para vetores de objeto, onde atualizações para o mesmo vetor podem interagir entre si.
• Eventos: condições de corrida não afetam eventos porque cada evento é único e tem um timestamp associado a ele.

A melhor maneira de evitar esse comportamento é garantir que os dados de origem da sua sincronização CDI reflitam apenas o estado mais recente de cada usuário, ou que todas as atualizações para um determinado usuário ou par usuário+atributo estejam contidas em uma única linha.

Criar uma string JSON a partir de outra tabela

Se você preferir armazenar cada atributo em sua própria coluna internamente, precisa converter essas colunas em uma string JSON para preencher a sincronização com a Braze. Para fazer isso, você pode usar uma 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] ;

Use o timestamp UPDATED_AT

A Braze usa o timestamp UPDATED_AT para rastrear quais dados foram sincronizados com sucesso. A CDI também rastreia o número de linhas no último timestamp sincronizado. Se novas linhas forem adicionadas com o mesmo timestamp entre as execuções, a CDI re-sincroniza todas as linhas naquele timestamp, o que pode levar a dados duplicados. Para mais detalhes e dicas, consulte Evitar re-sincronização de linhas com timestamps duplicados.

Configuração da tabela

Temos um repositório GitHub público para os clientes compartilharem melhores práticas ou trechos de código. Para contribuir com seus próprios trechos, crie um pull request!

Formatação de dados

Os requisitos de configuração de tabela e formatação de carga útil da Ingestão de Dados na Nuvem estão documentados em Configuração de tabela para Ingestão de Dados na Nuvem.

Use essa página para distinguir:

• Requisitos da tabela de origem (colunas obrigatórias, colunas de identificador e comportamento de UPDATED_AT)
• Requisitos de carga útil (quais campos devem corresponder ao formato de objeto /users/track para cada tipo de dados)

Evite timeouts para consultas de data warehouse

Recomendamos que as consultas sejam concluídas dentro de uma hora para obter desempenho ideal e evitar possíveis erros. Se as consultas excederem esse período, considere revisar a configuração do seu data warehouse. A otimização dos recursos alocados ao seu warehouse pode ajudar a melhorar a velocidade de execução da consulta.

Limitações do produto