Perguntas frequentes

Esta página contém respostas para algumas perguntas frequentes sobre a Ingestão de dados na nuvem.

Com que frequência uma sincronização de CDI pode ser executada?

Sincronizações recorrentes podem ser executadas a cada 5 minutos ou, no máximo, uma vez por mês. Por padrão, o menor intervalo que você pode definir no dashboard é de 15 minutos, o que ajuda a gerenciar os custos de computação do seu data warehouse e o volume de solicitações. Para sincronizar a cada 5 minutos, entre em contato com o suporte da Braze ou com o seu gerente de sucesso do cliente. Para sincronizar assim que seus dados forem alterados, chame o endpoint Disparar uma sincronização. Para saber mais, consulte Como funciona.

Por que recebi o e-mail: “Error in CDI Sync”?

Esse tipo de e-mail geralmente significa que há um problema na configuração da CDI. Veja alguns problemas comuns e como resolvê-los:

A CDI não consegue acessar o data warehouse ou a tabela usando suas credenciais

Isso pode significar que as credenciais na CDI estão incorretas ou configuradas de forma errada no data warehouse. Para saber mais, consulte Integrações com Data Warehouse.

A tabela não foi encontrada

Tente atualizar sua integração com a configuração correta do banco de dados ou crie os recursos correspondentes no data warehouse, como database/table.

O catálogo não foi encontrado

O catálogo configurado na integração não existe no catálogo da Braze. Um catálogo pode ser removido depois que a integração foi configurada. Para resolver o problema, atualize a integração para usar um catálogo diferente ou crie um novo catálogo que corresponda ao nome do catálogo na integração.

Por que recebi o e-mail: “Row errors in your CDI sync”?

Esse tipo de e-mail significa que alguns dos seus dados não puderam ser processados durante a sincronização. Para descobrir o erro específico, você pode revisar os logs na Braze acessando CDI > Sync Log.

Como corrigir o erro “Time must be string in ISO8601 Format” na configuração de CDI?

Esse erro significa que o valor de time do evento na sua carga útil de CDI não está em um formato de data e hora compatível.

Para cargas úteis de eventos e compras, formate time como:

• Uma string ISO 8601, ou
• yyyy-MM-dd'T'HH:mm:ss:SSSZ

Se time for omitido, a Braze usará UPDATED_AT como o horário do evento.

Para ver os requisitos completos de carga útil, consulte Configuração de tabelas para ingestão de dados na nuvem.

Como corrigir erros de Test Connection e e-mails de suporte?

• snowflake
• redshift
• bigquery
• databricks

Como atualizo minhas preferências de alerta por e-mail para integrações de CDI?

Cada integração tem sua própria preferência de notificação. Acesse a página de CDI e selecione o nome da integração que deseja atualizar. Na seção Notification preferences, você pode atualizar como recebe alertas referentes à integração selecionada.

Por que estou vendo o erro “Incorrect Integration Object”?

Esse erro ocorre quando você tenta atualizar as preferências de notificação de uma integração CDI e dois ou mais espaços de trabalho possuem integrações apontando para o mesmo bucket ou pasta de armazenamento em nuvem. Cada local de armazenamento em nuvem pode ser usado por apenas uma integração por vez.

Para resolver isso:

1. Identifique qual outro espaço de trabalho possui uma integração CDI usando o mesmo local de armazenamento.
2. Remova ou reconfigure a integração conflitante no outro espaço de trabalho.
3. Após remover o conflito, você poderá atualizar as preferências de notificação.

O erro não deve mais aparecer, e você poderá atualizar suas preferências de notificação com sucesso. Se ainda estiver enfrentando problemas, abra um ticket de suporte.

O que acontece se um UPDATED_AT futuro for sincronizado com uma integração?

A CDI usa UPDATED_AT para decidir quais dados são novos. Depois que um UPDATED_AT futuro é sincronizado, quaisquer dados anteriores a essa data e hora futura não serão processados. Para corrigir isso:

1. Corrija o UPDATED_AT.
2. Remova quaisquer dados antigos que já foram sincronizados com a Braze.
3. Crie uma nova integração para processar essa tabela novamente.

Por que “Rows Synced” não corresponde ao número no meu data warehouse?

O CDI usa UPDATED_AT para decidir quais registros devem ser coletados durante uma sincronização. Confira esta ilustração para entender como funciona. No início de uma execução de sincronização, o CDI consulta seu data warehouse para obter todos os registros com UPDATED_AT posterior ao último valor de UPDATED_AT processado. Registros exatamente no timestamp limite também podem ser ressincronizados se novas linhas compartilharem esse timestamp. Qualquer registro coletado no momento em que a consulta é executada é sincronizado na Braze. Veja os casos comuns em que um registro pode não ser sincronizado:

• Você está adicionando registros à tabela com um valor de UPDATED_AT que já foi processado.
• Você está atualizando valores de registros depois que eles foram processados por uma sincronização, mas deixando UPDATED_AT inalterado.
• Você está adicionando ou atualizando registros enquanto uma sincronização está em andamento. Dependendo de quando a consulta do CDI é executada, podem ocorrer condições de corrida que fazem com que registros não sejam coletados.

Dica

Para evitar esses comportamentos no futuro, recomendamos usar valores de UPDATED_AT monotonicamente crescentes e não atualizar a tabela durante a execução da sincronização agendada.

Preciso de valores UPDATED_AT majoritariamente distintos para grandes importações via CDI?

Sim. Para execuções de alto volume (por exemplo, mais de aproximadamente 10 milhões de linhas), certifique-se de que seus dados de origem tenham valores UPDATED_AT majoritariamente distintos. Se muitas linhas compartilharem o mesmo timestamp, é mais provável que o CDI reselecione linhas nos timestamps de fronteira em execuções posteriores. Isso pode aumentar sincronizações duplicadas e o consumo de pontos de dados.

Para saber mais sobre o comportamento de fronteira do CDI, consulte Evitar ressincronização de linhas com timestamps duplicados.

Onde executo essas verificações SQL?

Execute as verificações diretamente no editor SQL do seu data warehouse, na mesma tabela ou view usada pela sua integração CDI:

• Snowflake: Projects > Worksheets (para saber mais, consulte Snowflake Worksheets)
• Redshift: Query Editor v2 (para saber mais, consulte Using Amazon Redshift Query Editor v2)
• BigQuery: BigQuery Studio SQL workspace (para saber mais, consulte BigQuery Studio introduction)
• Databricks: SQL editor (SQL warehouse) (para saber mais, consulte Databricks SQL editor)
• Fabric: SQL query editor

Use este processo antes de ativar ou escalar uma sincronização grande:

1. Identifique a tabela ou view de origem CDI exata e a janela de sincronização que você deseja validar.
2. Abra o editor SQL do seu data warehouse e selecione o mesmo banco de dados e schema usados pelo CDI. Em seguida, use uma role com acesso de leitura à tabela ou view de origem.
3. Execute a consulta de contagem de timestamps distintos para medir quantos valores UPDATED_AT distintos existem naquela janela.
4. Execute a consulta que agrupa por UPDATED_AT e conta as linhas para encontrar timestamps com contagens de linhas anormalmente altas.
5. Se muitas linhas compartilharem timestamps idênticos, ajuste seu processo de ingestão para que lotes consecutivos usem valores UPDATED_AT progressivamente mais recentes, ou aumente a precisão do timestamp para que as linhas fiquem mais distribuídas.
6. Execute ambas as consultas novamente até que a concentração seja reduzida. Depois, inicie ou escale sua sincronização.
7. Após o lançamento, monitore CDI > Sync Log para verificar se há volume inesperado de ressincronização nos timestamps de fronteira.

Use verificações como estas no seu data warehouse:

1
2
3
4
5
6
7

SELECT
  COUNT(*) AS total_rows,
  COUNT(DISTINCT UPDATED_AT) AS distinct_timestamps,
  ROUND(COUNT(*) * 1.0 / NULLIF(COUNT(DISTINCT UPDATED_AT), 0), 2) AS avg_rows_per_timestamp
FROM YOUR_CDI_SOURCE_TABLE
WHERE UPDATED_AT >= CAST('2026-04-01 00:00:00' AS TIMESTAMP)
  AND UPDATED_AT < CAST('2026-04-02 00:00:00' AS TIMESTAMP);

1
2
3
4
5
6
7
8
9

SELECT
  UPDATED_AT,
  COUNT(*) AS rows_at_timestamp
FROM YOUR_CDI_SOURCE_TABLE
WHERE UPDATED_AT >= CAST('2026-04-01 00:00:00' AS TIMESTAMP)
  AND UPDATED_AT < CAST('2026-04-02 00:00:00' AS TIMESTAMP)
GROUP BY UPDATED_AT
ORDER BY rows_at_timestamp DESC
LIMIT 20;

Se o seu data warehouse não suportar LIMIT (por exemplo, Fabric), use uma sintaxe equivalente, como TOP.

Por que uma sincronização CDI com poucas linhas ainda pode levar vários minutos?

Uma sincronização CDI inclui um período fixo de inicialização antes de o processamento das linhas começar. Como esse tempo de inicialização é semelhante independentemente do tamanho da sincronização, uma sincronização pequena ainda pode levar vários minutos e parecer mais lenta em linhas por minuto. O tempo total de sincronização ainda depende da complexidade da consulta de origem, do formato dos dados e da capacidade disponível no seu data warehouse. Para saber mais, consulte Integrações com data warehouse.

Durante uma sincronização, a ordem é preservada se vários registros compartilham o mesmo ID?

A ordem de processamento não é 100% previsível. Por exemplo, se houver várias linhas com o mesmo EXTERNAL_ID na tabela durante uma sincronização, não é possível garantir qual valor ficará no perfil final. Se você estiver atualizando o mesmo EXTERNAL_ID com atributos diferentes na coluna de carga útil, todas as alterações serão refletidas quando a sincronização for concluída.

Por que novos usuários não estão sendo criados a partir da minha sincronização CDI?

Se a sua integração CDI tiver a opção Update existing users only ativada, apenas os usuários que já existem na Braze serão atualizados, e novos usuários não serão criados. Isso significa que, se uma linha na sua tabela de sincronização fizer referência a um EXTERNAL_ID que não corresponde a nenhum usuário existente na Braze, essa linha será ignorada.

Para criar novos usuários por meio do CDI, desative o toggle Update existing users only nas configurações da sua integração. Acesse Data Settings > Cloud Data Ingestion e selecione uma integração.

Quais são as medidas de segurança para CDI?

Nossas medidas

A Braze tem as seguintes medidas implementadas para CDI:

• Todas as credenciais são criptografadas em nosso banco de dados, e apenas determinados colaboradores têm acesso autenticado a elas.
• Utilizamos conexões criptografadas para enviar dados aos data warehouses dos clientes.
• Fazemos solicitações aos endpoints da API da Braze usando as mesmas chaves de API e conexões TLS que recomendamos que nossos clientes utilizem.
• Atualizamos regularmente nossas bibliotecas e aplicamos todas as correções de segurança.

Suas medidas

Recomendamos que você e sua equipe configurem as seguintes medidas de segurança do seu lado:

• Restrinja o acesso às credenciais ao mínimo necessário para que o CDI funcione. Isso porque precisamos ser capazes de executar select (e count) nas tabelas e views específicas.
• Restrinja os IPs que podem acessar as tabelas aos IPs da Braze oficialmente publicados.