Erreurs courantes
Le test des privilèges a échoué ou certaines opérations échouent en raison des autorisations
ALTER, CREATE DATABASE, CREATE TABLE, INSERT et SELECT sur *.* (toutes les bases de données et toutes les tables).
La vérification des privilèges interroge
system.grants et ne prend en compte que les privilèges accordés directement à l’utilisateur. Les privilèges attribués via un rôle ClickHouse ne sont pas détectés. Consultez la section privilèges accordés via des rôles pour plus de détails.Erreur lors de l’attente de l’achèvement de toutes les mutations
ALTER TABLE ... UPDATE ou ALTER TABLE ... DELETE a été soumise, mais le délai d’attente du connecteur a expiré avant qu’elle ne se termine sur toutes les répliques. La partie « initial cause » de l’erreur contient souvent l’erreur ClickHouse d’origine (généralement le code 341, « Unfinished »).
Cela peut se produire dans les cas suivants :
- Le cluster ClickHouse Cloud est fortement sollicité.
- Un ou plusieurs nœuds sont tombés en panne pendant l’exécution de la mutation.
- Vérifier la progression de la mutation : Exécutez la requête suivante pour rechercher d’éventuelles mutations en attente :
- Vérifier l’état du cluster : Assurez-vous que tous les nœuds sont en bon état.
- Attendre et réessayer : Les mutations finissent par s’achever une fois le cluster rétabli. Fivetran relancera automatiquement la synchronisation.
Erreur de discordance des colonnes
- Des colonnes ont été ajoutées ou supprimées manuellement dans la table ClickHouse.
- Une modification du schéma dans la source n’a pas été correctement propagée.
- N’oubliez pas : ne modifiez pas manuellement les tables gérées par Fivetran. Voir les bonnes pratiques.
- Rétablissez le type de la colonne : Si vous savez quel type la colonne doit avoir, rétablissez-la au type attendu en vous appuyant sur le mapping de transformation des types.
- Relancez la synchronisation de la table : Dans le tableau de bord Fivetran, déclenchez une resynchronisation historique pour la table concernée.
- Supprimez, puis recréez : En dernier recours, supprimez la table de destination et laissez Fivetran la recréer lors de la prochaine synchronisation.
AST trop volumineux (code 168)
mutation_batch_size et hard_delete_batch_size dans le fichier de configuration avancée. Les deux ont une valeur par défaut de 1500 et acceptent des valeurs comprises entre 200 et 1500.
Dépassement de la limite de mémoire / OOM (code 241)
INSERT nécessite plus de mémoire que la mémoire disponible. Cela se produit généralement lors de synchronisations initiales volumineuses, avec des tables comportant de nombreuses colonnes, ou lors d’opérations par lot concurrentes.
Solutions :
- Réduisez
write_batch_size: essayez de le ramener à 50 000 pour les grandes tables. - Réduisez la charge de la base de données : vérifiez la charge du service ClickHouse Cloud pour voir s’il est surchargé.
- Augmentez la capacité du service ClickHouse Cloud pour disposer de plus de mémoire.
EOF inattendue / Erreur de connexion
FAILURE_WITH_TASK sans stack trace dans les logs Fivetran.
Cause :
- La liste d’accès IP n’est pas configurée pour autoriser le trafic Fivetran.
- Problèmes réseau transitoires entre Fivetran et ClickHouse Cloud.
- Des données source corrompues ou invalides provoquent le plantage du connecteur de destination.
- Vérifiez la liste d’accès IP : dans ClickHouse Cloud, accédez à Paramètres > Sécurité et ajoutez les adresses IP de Fivetran, ou autorisez l’accès depuis n’importe quelle adresse.
- Réessayez : les versions récentes du connecteur réessaient automatiquement en cas d’erreurs EOF. Les erreurs sporadiques (1 à 2 par jour) sont probablement temporaires.
- Si le problème persiste : ouvrez un ticket de support auprès de ClickHouse en indiquant la période durant laquelle l’erreur s’est produite. Demandez également au support Fivetran d’examiner la qualité des données source.
Impossible de mapper le type UInt64
LONG à Int64, jamais à UInt64. Cette erreur se produit lorsqu’un type de colonne est modifié manuellement dans une table gérée par Fivetran.
Solutions :
- Ne modifiez pas manuellement les types de colonnes dans les tables gérées par Fivetran.
- Pour corriger le problème : rétablissez le type attendu pour la colonne (par exemple,
Int64) ou supprimez puis resynchronisez la table. - Pour les types personnalisés : créez une vue matérialisée sur la table gérée par Fivetran.
Pas de clé primaire pour la table
ORDER BY. Lorsque la source n’a pas de clé primaire, Fivetran ajoute automatiquement _fivetran_id. Cette erreur survient dans certains cas particuliers où la source définit une clé primaire, mais où les données ne la contiennent pas.
Solutions :
- Contactez l’assistance Fivetran pour examiner le pipeline source.
- Vérifiez le schéma de la source : assurez-vous que les colonnes de clé primaire sont présentes dans les données.
Échec des privilèges accordés via un rôle
user_name = NULL et role_name = 'my_role' ; ils ne sont donc pas pris en compte par cette vérification.
Solution :
Accordez les privilèges directement à l’utilisateur Fivetran :
Bonnes pratiques
Service ClickHouse dédié à Fivetran
- Service A (writer): destination Fivetran + autres outils d’ingestion (ClickPipes, connecteurs Kafka)
- Service B (reader): outils de BI, tableaux de bord, requêtes ad hoc
Optimiser les requêtes de lecture
SharedReplacingMergeTree pour les tables de destination Fivetran, qui est la version du moteur de table ReplacingMergeTree dans ClickHouse Cloud. La présence de lignes en double avec la même clé primaire est normale — la déduplication s’effectue de manière asynchrone lors des merges en arrière-plan. Lors de la lecture, veillez à ne pas renvoyer de lignes en double, car certaines n’ont peut-être pas encore été dédupliquées.
Utiliser le mot-clé FINAL est le moyen le plus simple d’éviter les lignes en double, car il force la fusion des lignes qui n’ont pas encore été dédupliquées au moment de la lecture :
FINAL — par exemple, en filtrant sur les colonnes de clé à l’aide d’une condition WHERE. Pour en savoir plus, consultez la section performances de FINAL du guide ReplacingMergeTree.
Si ces optimisations ne suffisent pas, vous disposez d’autres options qui évitent d’utiliser FINAL tout en gérant correctement les doublons :
- Si vous voulez interroger une colonne numérique dont la valeur ne fait qu’augmenter, vous pouvez utiliser
max(the_column). - Si vous devez récupérer la valeur la plus récente de certaines colonnes pour une clé donnée, vous pouvez utiliser
argMax(the_column, _fivetran_id).
Optimisation de la clé primaire et du
ORDER BY. Lorsque la source n’a pas de PK, _fivetran_id (un UUID) devient la clé de tri, ce qui peut dégrader les performances des requêtes, car ClickHouse construit son index primaire épars à partir des colonnes de ORDER BY.
Recommandations dans ce cas, si aucune autre optimisation n’est suffisante :
- Traitez les tables Fivetran comme des tables de staging brutes. Ne les interrogez pas directement à des fins analytiques.
- Si les requêtes ne sont toujours pas assez performantes, utilisez une vue matérialisée actualisable pour créer une copie de la table avec un
ORDER BYoptimisé pour vos modèles de requêtes. Contrairement aux vues matérialisées incrémentales, les vues matérialisées actualisables réexécutent la requête complète selon une planification définie, ce qui gère correctement les opérationsUPDATEetDELETEémises par Fivetran lors des synchronisations :
Évitez les vues matérialisées incrémentales (non actualisables) pour les tables gérées par Fivetran. Comme Fivetran émet des opérations
UPDATE et DELETE pour maintenir la synchronisation des données, les vues matérialisées incrémentales ne refléteront pas ces changements et contiendront des données obsolètes ou incorrectes.Ne modifiez pas manuellement les tables gérées par Fivetran
ALTER TABLE ... MODIFY COLUMN) sur les tables gérées par Fivetran. Le connecteur s’attend au schéma qu’il a créé. Les modifications manuelles peuvent provoquer des erreurs de mappage de types et des incompatibilités de schéma.
Utilisez des vues matérialisées pour les transformations personnalisées.
Débogage des opérations
- Consultez le
system.query_logde ClickHouse pour les problèmes côté serveur. - Demandez de l’aide à Fivetran pour les problèmes côté client.