Erros comuns
O teste de grant falhou ou as operações estão falhando devido a permissões
ALTER, CREATE DATABASE, CREATE TABLE, INSERT e SELECT em *.* (todos os bancos de dados e tabelas).
A verificação de privilégios consulta
system.grants e só considera privilégios concedidos diretamente ao usuário. Privilégios atribuídos por meio de uma role do ClickHouse não são detectados. Consulte a seção grant baseado em role para mais detalhes.Erro ao aguardar a conclusão de todas as mutações
ALTER TABLE ... UPDATE ou ALTER TABLE ... DELETE foi enviada, mas o conector atingiu o tempo limite enquanto aguardava sua conclusão em todas as réplicas. A parte “causa inicial” do erro geralmente contém o erro original do ClickHouse (normalmente o código 341, “Unfinished”).
Isso pode acontecer quando:
- O cluster do ClickHouse Cloud está sob carga intensa.
- Um ou mais nós ficaram indisponíveis durante a execução da mutação.
- Verifique o progresso da mutação: Execute a consulta abaixo para verificar se há mutações pendentes:
- Verifique a integridade do cluster: Garanta que todos os nós estejam saudáveis.
- Aguarde e tente novamente: As mutações acabam sendo concluídas quando o cluster volta a ficar saudável. O Fivetran tentará sincronizar novamente automaticamente.
Erro de incompatibilidade de colunas
- Colunas foram adicionadas ou removidas manualmente da tabela no ClickHouse.
- Uma alteração no esquema da origem não foi propagada corretamente.
- Lembre-se de não modificar manualmente tabelas gerenciadas pelo Fivetran. Veja boas práticas.
- Altere a coluna de volta: Se você souber qual deve ser o tipo da coluna, altere-a de volta para o tipo esperado usando o mapeamento de transformação de tipos como referência.
- Sincronize a tabela novamente: No dashboard do Fivetran, acione uma resincronização histórica da tabela afetada.
- Exclua e recrie: Como último recurso, exclua a tabela de destino e deixe o Fivetran recriá-la durante a próxima sincronização.
AST é grande demais (código 168)
mutation_batch_size e hard_delete_batch_size no arquivo de configuração avançada. Ambos têm valor padrão de 1500 e aceitam valores entre 200 e 1500.
Limite de memória excedido / OOM (código 241)
INSERT exige mais memória do que a disponível. Isso geralmente acontece durante grandes sincronizações iniciais, com tabelas com muitas colunas ou operações em lote simultâneas.
Soluções:
- Reduza
write_batch_size: Tente diminuí-lo para 50.000 em tabelas grandes. - Reduza a carga do banco de dados: Verifique a carga no serviço ClickHouse Cloud para ver se ele está sobrecarregado.
- Escalone o serviço ClickHouse Cloud para disponibilizar mais memória.
EOF inesperado / Erro de conexão
FAILURE_WITH_TASK sem stack trace nos logs do Fivetran.
Causa:
- Lista de acesso por IP não configurada para permitir o tráfego do Fivetran.
- Problemas transitórios de rede entre o Fivetran e o ClickHouse Cloud.
- Dados de origem corrompidos ou inválidos fazendo o conector de destino travar.
- Verifique a lista de acesso por IP: No ClickHouse Cloud, vá para Settings > Security e adicione os endereços IP do Fivetran ou permita acesso de qualquer origem.
- Tente novamente: As versões mais recentes do conector fazem nova tentativa automaticamente após erros de EOF. Erros esporádicos (1–2 por dia) provavelmente são transitórios.
- Se o problema persistir: Abra um ticket de suporte com a ClickHouse informando o intervalo de tempo em que ocorreu o erro. Também peça ao suporte da Fivetran para investigar a qualidade dos dados de origem.
Não foi possível mapear o tipo UInt64
LONG para Int64, nunca para UInt64. Esse erro ocorre quando o tipo de uma coluna é alterado manualmente em uma tabela gerenciada pelo Fivetran.
Soluções:
- Não modifique manualmente os tipos das colunas em tabelas gerenciadas pelo Fivetran.
- Para corrigir: Altere a coluna de volta para o tipo esperado (por exemplo,
Int64) ou exclua e sincronize novamente a tabela. - Para tipos personalizados: Crie uma visão materializada sobre a tabela gerenciada pelo Fivetran.
Sem chave primária para a tabela
ORDER BY. Quando a fonte não tem chave primária, o Fivetran adiciona _fivetran_id automaticamente. Esse erro ocorre em casos excepcionais em que a fonte define uma chave primária, mas os dados não a contêm.
Soluções:
- Entre em contato com o suporte da Fivetran para investigar o pipeline da fonte.
- Verifique o esquema da fonte: Garanta que as colunas da chave primária estejam presentes nos dados.
Falha nos grant baseados em role
user_name = NULL e role_name = 'my_role', portanto não são detectados por esta verificação.
Solução:
Conceda privilégios diretamente ao usuário do Fivetran:
Boas práticas
Serviço ClickHouse dedicado para o Fivetran
- Serviço A (writer): destino do Fivetran + outras ferramentas de ingestão (ClickPipes, conectores do Kafka)
- Serviço B (reader): ferramentas de BI, dashboards, consultas ad hoc
Otimizando consultas de leitura
SharedReplacingMergeTree para tabelas de destino do Fivetran, que é a versão do mecanismo de tabela ReplacingMergeTree no ClickHouse Cloud. Linhas duplicadas com a mesma chave primária são normais — a desduplicação acontece de forma assíncrona durante as mesclagens em segundo plano. No momento da leitura, é preciso ter cuidado para evitar retornar linhas duplicadas, pois algumas delas ainda podem não ter sido desduplicadas.
Usar a palavra-chave FINAL é a forma mais simples de evitar linhas duplicadas, pois ela força a mesclagem de quaisquer linhas que ainda não tenham sido desduplicadas no momento da leitura:
FINAL — por exemplo, filtrando pelas colunas-chave usando uma condição WHERE. Para mais detalhes, consulte a seção desempenho do FINAL do guia ReplacingMergeTree.
Se essas otimizações não forem suficientes, há opções adicionais que evitam o uso de FINAL e ainda lidam corretamente com duplicatas:
- Se você quiser consultar uma coluna numérica que está sempre aumentando, pode usar
max(the_column). - Se você precisar recuperar o valor mais recente de algumas colunas para uma chave específica, pode usar
argMax(the_column, _fivetran_id).
O Fivetran replica a chave primária da tabela de origem como a cláusula
ORDER BY do ClickHouse. Quando a origem não tem PK, _fivetran_id (um UUID) se torna a chave de ordenação, o que pode levar a baixo desempenho nas consultas, porque o ClickHouse constrói seu índice primário esparso a partir das colunas de ORDER BY.
Recomendações nesse caso, se nenhuma outra otimização for suficiente:
- Trate as tabelas do Fivetran como tabelas de staging de dados brutos. Não faça consultas analíticas diretamente nelas.
- Se as consultas ainda não tiverem desempenho suficiente, use uma visão materializada atualizável para criar uma cópia da tabela com um
ORDER BYotimizado para seus padrões de consulta. Ao contrário das visões materializadas incrementais, visões materializadas atualizáveis reexecutam a consulta completa de acordo com uma programação, o que lida corretamente com as operaçõesUPDATEeDELETEque o Fivetran emite durante as sincronizações:
Evite visões materializadas incrementais (não atualizáveis) para tabelas gerenciadas pelo Fivetran. Como o Fivetran emite operações
UPDATE e DELETE para manter os dados sincronizados, visões materializadas incrementais não refletirão essas mudanças e conterão dados desatualizados ou incorretos.Não modifique manualmente tabelas gerenciadas pelo Fivetran
ALTER TABLE ... MODIFY COLUMN) em tabelas gerenciadas pelo Fivetran. O conector espera o esquema que ele criou. Alterações manuais podem causar erros de mapeamento de tipos e falhas por incompatibilidade de esquema.
Use visões materializadas para transformações personalizadas.
Operações de depuração
- Verifique o
system.query_logdo ClickHouse para identificar problemas no lado do servidor. - Peça ajuda à Fivetran para problemas no lado do cliente.