Solução de problemas e práticas recomendadas

Mensagem de erro:

Test grants failed, cause: user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT

Causa: O usuário do Fivetran não tem os privilégios necessários. O conector exige os privilégios ALTER, CREATE DATABASE, CREATE TABLE, INSERT e SELECT em *.* (todos os bancos de dados e tabelas).

Solução:

Conceda os privilégios necessários diretamente ao usuário do Fivetran:

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

Mensagem de erro:

error while waiting for all mutations to be completed: ... initial cause: ...

Causa: Uma mutação 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.

Soluções:

1. Verifique o progresso da mutação: Execute a consulta abaixo para verificar se há mutações pendentes:

   SELECT database, table, mutation_id, command, create_time, is_done
   FROM system.mutations
   WHERE NOT is_done
   ORDER BY create_time DESC;

2. Verifique a integridade do cluster: Garanta que todos os nós estejam saudáveis.
3. 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.

Mensagem de erro:

Erros diferentes podem ocorrer se a incompatibilidade de colunas for causada por uma alteração de esquema na origem. Por exemplo:

columns count in ClickHouse table (8) does not match the input file (6). Expected columns: id, name, ..., got: id, name, ...

Ou:

column user_email was not found in the table definition. Table columns: ...; input file columns: ...

Causa: As colunas da tabela de destino no ClickHouse não correspondem às colunas dos dados que estão sendo sincronizados. Isso pode acontecer quando:

• Colunas foram adicionadas ou removidas manualmente da tabela no ClickHouse.
• Uma alteração no esquema da origem não foi propagada corretamente.

Soluções:

1. Lembre-se de não modificar manualmente tabelas gerenciadas pelo Fivetran. Veja boas práticas.
2. 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.
3. Sincronize a tabela novamente: No dashboard do Fivetran, acione uma resincronização histórica da tabela afetada.
4. Exclua e recrie: Como último recurso, exclua a tabela de destino e deixe o Fivetran recriá-la durante a próxima sincronização.

Mensagem de erro:

code: 168, message: AST is too big. Maximum: 50000

ou

code: 62, message: Max query size exceeded

Causa: Grandes lotes de UPDATE ou DELETE geram instruções SQL com árvores de sintaxe abstrata muito complexas. Isso é comum em tabelas com muitas colunas ou com o modo de histórico habilitado.

Solução:

Reduza 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.

Mensagem de erro:

code: 241, message: (total) memory limit exceeded: would use 14.01 GiB

Causa: A operação 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:

1. Reduza write_batch_size: Tente diminuí-lo para 50.000 em tabelas grandes.
2. Reduza a carga do banco de dados: Verifique a carga no serviço ClickHouse Cloud para ver se ele está sobrecarregado.
3. Escalone o serviço ClickHouse Cloud para disponibilizar mais memória.

Mensagem de erro:

ClickHouse connection error: unexpected EOF

Ou 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.

Soluções:

1. 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.
2. 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.
3. 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.

Mensagem de erro:

cause: can't map type UInt64 to Fivetran types

Causa: O conector mapeia 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:

1. Não modifique manualmente os tipos das colunas em tabelas gerenciadas pelo Fivetran.
2. Para corrigir: Altere a coluna de volta para o tipo esperado (por exemplo, Int64) ou exclua e sincronize novamente a tabela.
3. Para tipos personalizados: Crie uma visão materializada sobre a tabela gerenciada pelo Fivetran.

Mensagem de erro:

Failed to alter table ... cause: no primary keys for table

Causa: Toda tabela do ClickHouse exige um 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:

1. Entre em contato com o suporte da Fivetran para investigar o pipeline da fonte.
2. Verifique o esquema da fonte: Garanta que as colunas da chave primária estejam presentes nos dados.

Mensagem de erro:

user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT

Causa: O conector verifica os grant com:

SELECT access_type, database, table, column FROM system.grants WHERE user_name = 'my_user'

Isso retorna apenas grant diretos. Os privilégios atribuídos por meio de uma role do ClickHouse têm 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:

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

Em caso de alta carga de ingestão, considere usar a compute-compute separation do ClickHouse Cloud para criar um serviço dedicado às cargas de trabalho de gravação do Fivetran. Isso isola a ingestão das consultas analíticas e evita a contenção de recursos.

Por exemplo, a arquitetura a seguir pode ser usada:

• 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

O ClickHouse usa 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:

SELECT * FROM schema.table FINAL WHERE ...

Há formas de otimizar essa operação 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:

1. Trate as tabelas do Fivetran como tabelas de staging de dados brutos. Não faça consultas analíticas diretamente nelas.
2. 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 BY otimizado 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ções UPDATE e DELETE que o Fivetran emite durante as sincronizações:

   CREATE MATERIALIZED VIEW schema.table_optimized
   REFRESH EVERY 1 HOUR
   ENGINE = ReplacingMergeTree()
   ORDER BY (user_id, event_date)
   AS SELECT * FROM schema.table_raw FINAL;

Evite alterações manuais de DDL (por exemplo, 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.

Ao diagnosticar falhas:

• Verifique o system.query_log do ClickHouse para identificar problemas no lado do servidor.
• Peça ajuda à Fivetran para problemas no lado do cliente.

Para bugs no conector, crie uma issue no GitHub ou entre em contato com o suporte do ClickHouse.

Use as consultas a seguir para diagnosticar falhas de sincronização no ClickHouse.

SELECT event_time, query, exception_code, exception
FROM system.query_log
WHERE client_name LIKE 'fivetran-destination%'
  AND exception_code > 0
ORDER BY event_time DESC
LIMIT 50;

SELECT event_time, query_kind, query, exception_code, exception
FROM system.query_log
WHERE user = '{fivetran_user}'
ORDER BY event_time DESC
LIMIT 100;