Melhores práticas

A Ingestão de Dados na Nuvem da Braze permite configurar uma conexão direta do seu data warehouse ou sistema de armazenamento de arquivos com a Braze para sincronizar dados relevantes de usuários ou catálogos. Ao sincronizar esses dados com a Braze, você pode alavancá-los em casos de uso como personalização, disparo ou segmentação.

Rastreie alterações com UPDATED_AT

Nota

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

Quando uma sincronização é executada, a Braze se conecta diretamente à sua instância de data warehouse e usa o timestamp UPDATED_AT de cada linha para rastreamento de alterações. UPDATED_AT é um campo obrigatório para todas as sincronizações com data warehouse.

Importante

O CDI rastreia alterações estritamente com base nos valores de UPDATED_AT, independentemente de o conteúdo da linha ser igual ao que está atualmente na Braze. A Braze recomenda usar UPDATED_AT para sincronizar apenas dados novos ou atualizados, o que evita uso desnecessário de pontos de dados.

Exemplo: comportamento de sincronização recorrente

Para ilustrar como UPDATED_AT é usado em uma sincronização CDI, veja este exemplo de sincronização recorrente para atualização de atributos de usuários.

Cada vez que uma sincronização é executada, o CDI procura por linhas que não foram sincronizadas anteriormente. O CDI verifica isso usando a coluna UPDATED_AT na sua tabela ou view. A Braze seleciona e importa todas as linhas em que UPDATED_AT é posterior ao último valor de UPDATED_AT sincronizado. Linhas no timestamp exato do limite também podem ser ressincronizadas se novas linhas forem adicionadas com o mesmo timestamp entre as execuções.

Importante

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

No seu data warehouse, adicione os seguintes usuários e atributos à sua tabela, definindo o horário de UPDATED_AT como o momento em que você adiciona 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 agendada, 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 de usuário completo a cada vez. Após a sincronização, os perfis de usuário 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 de 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. Porém, a linha existente para customer_5678 tem um valor de UPDATED_AT igual ao timestamp armazenado, então ela é ressincronizada devido ao limite inclusivo. Para mais detalhes sobre esse comportamento, consulte Evite ressincronizar linhas com timestamps duplicados. 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 de 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 é definido como 2022-07-21 08:30:00.

Nota

É permitido que os valores de UPDATED_AT sejam até posteriores ao horário de início da execução de uma determinada sincronização. No entanto, isso não é recomendado, pois empurra o último timestamp de UPDATED_AT “para o futuro” e sincronizações subsequentes não sincronizarão valores anteriores.

Evite problemas com tipos de dados

Ao usar a CDI para sincronizar dados de fontes externas (como Databricks ou Snowflake), confira se as colunas de origem usam os tipos de dados corretos antes da sincronização. Os problemas mais comuns são:

• Timestamps armazenados como strings: Suas colunas de data devem usar um tipo timestamp ou datetime no banco de dados de origem, e não varchar ou string.
• Números armazenados como strings: Converta as colunas numéricas para os tipos integer ou float na consulta de origem antes de sincronizar.
• Tipos inconsistentes entre sincronizações: Se o tipo de uma coluna mudar entre uma sincronização e outra, a Braze pode rejeitar os novos dados. Verifique se o esquema de origem se mantém consistente.

Para forçar ou alterar os 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, Braze ID, e-mail ou número de telefone. Também é possível excluir usuários por ID externo, alias de usuário ou Braze ID.

Use um carimbo de data/hora UTC na coluna UPDATED_AT

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

Evitar a ressincronizaçã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 resselecionar 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 ressincroniza 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 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 resselecionadas após terem sido processadas.

Exemplo: gerenciando atualizações subsequentes

Este 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 transformar esses dados em uma coluna PAYLOAD, 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 da 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 (marcados com *):

Agora você precisa adicionar apenas os valores alterados na tabela de origem da CDI. Essas linhas podem ser anexadas em vez de atualizar as linhas antigas. A 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

Grave apenas atributos novos ou atualizados para minimizar o consumo

Sempre que uma sincronização é executada, a Braze procura linhas que ainda não foram sincronizadas. Fazemos essa verificação usando a coluna UPDATED_AT na sua tabela ou visualização. A Braze seleciona e importa todas as linhas em que UPDATED_AT é posterior ao último valor de UPDATED_AT sincronizado, mesmo que sejam iguais ao que já está no perfil do usuário. As linhas com o timestamp limite também podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp. Por isso, recomendamos sincronizar apenas os atributos que você quer adicionar ou atualizar.

O uso de pontos de dados com a CDI é idêntico ao de outros métodos de ingestão, como REST APIs ou SDKs. Então, cabe a você garantir que apenas atributos novos ou atualizados sejam adicionados às suas tabelas de origem.

Separe EXTERNAL_ID da coluna PAYLOAD

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

Remova um atributo

Em uma coluna PAYLOAD, você pode definir um atributo como null se quiser omiti-lo do perfil de um usuário. Se quiser que um atributo permaneça inalterado, não o envie para a Braze até que ele seja atualizado. Para remover um atributo completamente, 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 houver atualizações simultâneas.

Importante

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

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

Crie uma string JSON a partir de outra tabela

Se você usa uma coluna PAYLOAD e armazena internamente cada atributo em sua própria coluna, converta essas colunas em uma string JSON para preencher PAYLOAD. Para sincronizar colunas separadas sem criar uma string JSON, use a opção Visual ou SQL. Para saber mais, consulte Escolha uma opção de definição de dados.

Cada página de origem tem um exemplo prático no dialeto SQL do respectivo data warehouse:

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

Por exemplo, no 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";

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 esse mesmo timestamp entre as execuções, a CDI sincroniza novamente todas as linhas desse timestamp, o que pode gerar dados duplicados. Para mais detalhes e dicas, consulte Evite sincronizar novamente linhas com timestamps duplicados.

Configuração da tabela

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

Formatação de dados

Os requisitos de configuração de tabela e de formatação da carga útil da Cloud Data Ingestion estão documentados em Configuração de tabela para a Cloud Data Ingestion.

Use essa página para diferenciar:

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

Evite timeouts em consultas ao data warehouse

Recomendamos que as consultas sejam concluídas em até uma hora para garantir a melhor performance e evitar possíveis erros. Se as consultas ultrapassarem esse tempo, considere revisar a configuração do seu data warehouse. Otimizar os recursos alocados ao seu warehouse pode ajudar a aumentar a velocidade de execução das consultas.

Limitações do produto