Perguntas frequentes

Esta página contém respostas para algumas perguntas frequentes sobre o Cloud Data Ingestion.

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

As sincronizações recorrentes podem ser executadas a cada 5 minutos ou apenas uma vez por mês. Por padrão, o menor intervalo que você pode definir no dashboard é de 15 minutos. Isso ajuda a controlar 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 seu gerente de sucesso do cliente. Para sincronizar assim que seus dados mudarem, 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 indica um problema na sua configuração de CDI. Veja alguns problemas comuns e como resolvê-los:

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

Isso pode significar que as credenciais na CDI estão incorretas ou mal configuradas no data warehouse. Para saber mais, consulte as etapas de configuração na sua página de origem.

A tabela não foi encontrada

Tente atualizar sua integração com a configuração correta do banco de dados ou crie 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 ter sido removido depois que a integração foi configurada. Para resolver o problema, atualize a integração para usar outro catálogo ou crie um novo catálogo com o mesmo nome definido na integração.

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

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

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

Esse erro significa que o valor time do evento na sua carga útil da 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 usa UPDATED_AT como horário do evento.

Para conhecer todos os requisitos da carga útil, consulte Configuração de tabelas para a ingestão de dados na nuvem.

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

O Test Connection é executado no seu data warehouse. Por isso, aumentar a capacidade do warehouse pode deixá-lo mais rápido. Uma instância SQL serverless reduz o tempo de aquecimento e melhora a taxa de transferência das consultas, mas os custos de integração podem ficar um pouco mais altos.

Para mensagens de erro específicas da sua fonte, consulte a seção de solução de problemas na página dela:

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

Cada integração tem a 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 Preferências de notificação, você pode escolher como quer receber alertas sobre a 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 de CDI e dois ou mais espaços de trabalho têm integrações apontando para o mesmo bucket ou pasta de armazenamento em nuvem. Cada local de armazenamento em nuvem só pode ser usado por uma integração por vez.

Para resolver isso:

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

O erro não deve mais aparecer, e você deve conseguir atualizar suas preferências de notificação. Se o problema continuar, abra um ticket de suporte.

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

A CDI usa o UPDATED_AT para decidir quais dados são novos. Depois que um UPDATED_AT futuro é sincronizado, nenhum dado anterior a essa data e hora futuras será processado. Para corrigir isso:

1. Corrija o UPDATED_AT.
2. Remova todos os 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?

A CDI usa UPDATED_AT para decidir quais registros coletar durante uma sincronização. Confira esta ilustração para ver como funciona. No início de uma execução de sincronização, a CDI consulta seu data warehouse para obter todos os registros com UPDATED_AT posterior ao último valor de UPDATED_AT processado. Registros com o timestamp exato do limite também podem ser sincronizados novamente se novas linhas compartilharem esse timestamp. Todo registro coletado no momento em que a consulta é executada é sincronizado na Braze. Veja alguns 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 sem alterar o UPDATED_AT.
• Você está adicionando ou atualizando registros enquanto uma sincronização está em andamento. Dependendo de quando a consulta da CDI é executada, podem ocorrer condições de corrida que fazem com que alguns registros não sejam coletados.

Dica

Para evitar esses comportamentos no futuro, recomendamos usar valores de UPDATED_AT que aumentem de forma monotônica e não atualizar a tabela durante a execução agendada da sincronização.

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

Sim. Em execuções de alto volume (por exemplo, com mais de aproximadamente 10 milhões de linhas), confira se os dados de origem têm valores de UPDATED_AT majoritariamente distintos. Se muitas linhas compartilharem o mesmo registro de data e hora, a CDI tem mais chances de selecionar novamente as linhas nos registros de data e hora de limite em execuções posteriores. Isso pode aumentar as sincronizações duplicadas e o consumo de pontos de dados.

Para saber mais sobre o comportamento de limite da CDI, consulte Evite ressincronizar linhas com registros de data e hora duplicados.

Onde executo essas verificações em SQL?

Execute as verificações diretamente no editor SQL do seu data warehouse, na mesma tabela ou visualização usada pela sua integração de 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: espaço de trabalho SQL do BigQuery Studio (para saber mais, consulte BigQuery Studio introduction)
• Databricks: editor SQL (SQL warehouse) (para saber mais, consulte Databricks SQL editor)
• Fabric: editor de consultas SQL

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

1. Identifique exatamente a tabela ou visualização de origem da CDI e a janela de sincronização que você quer validar.
2. Abra o editor SQL do seu warehouse e selecione o mesmo banco de dados e esquema usados pela CDI. Em seguida, use uma função com acesso de leitura à tabela ou visualização de origem.
3. Execute a consulta de contagem de registros de data e hora distintos para medir quantos valores distintos de UPDATED_AT existem nessa janela.
4. Execute a consulta que agrupa por UPDATED_AT e conta as linhas para encontrar registros de data e hora com quantidades de linhas excepcionalmente altas.
5. Se muitas linhas compartilharem registros de data e hora idênticos, ajuste seu processo de ingestão para que lotes consecutivos usem valores de UPDATED_AT progressivamente mais recentes, ou aumente a precisão do registro de data e hora para distribuir melhor as linhas.
6. Execute as duas consultas novamente até reduzir a concentração. Depois, inicie ou escale sua sincronização.
7. Após o lançamento, monitore CDI > Sync Log para identificar volumes inesperados de ressincronização nos registros de data e hora de limite.

Use verificações como estas no seu 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 warehouse não for compatível com LIMIT (por exemplo, o Fabric), use uma sintaxe equivalente, como TOP.

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

Uma sincronização de CDI inclui um período fixo de inicialização antes de começar a processar as linhas. Como esse tempo de inicialização é parecido para sincronizações de qualquer tamanho, uma sincronização pequena ainda pode levar vários minutos e parecer mais lenta em linhas por minuto. O tempo total da sincronização também depende da complexidade da consulta de origem, do formato dos dados e da capacidade disponível no seu data warehouse. Para saber mais, consulte Fontes de ingestão de dados na nuvem.

Durante uma sincronização, a ordem é preservada se vários registros tiverem 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 podemos 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 na minha sincronização do CDI?

Se a sua integração do CDI estiver com a opção Atualizar apenas usuários existentes ativada, somente os usuários que já existem na Braze serão atualizados, e nenhum usuário novo será criado. Ou seja, se uma linha da 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 pelo CDI, desative a opção Atualizar apenas usuários existentes nas configurações da sua integração. Acesse Configurações de dados > Ingestão de dados na nuvem e selecione uma integração.

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

Nossas medidas

A Braze adota as seguintes medidas para a CDI:

• Todas as credenciais são criptografadas em nosso banco de dados, e apenas determinados colaboradores têm acesso autenticado a elas.
• Usamos conexões criptografadas para obter dados dos 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 aos nossos clientes.
• Atualizamos regularmente nossas bibliotecas e aplicamos todos os patches de segurança.

Suas medidas

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

• Restrinja o acesso das credenciais ao mínimo necessário para o funcionamento da CDI. Isso porque precisamos conseguir executar select (e count) nas tabelas e visualizações específicas.
• Restrinja os IPs que podem acessar as tabelas aos IPs oficialmente publicados pela Braze. Cada página de fonte lista os IPs que devem ser permitidos para aquela fonte.