> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Erreurs courantes, conseils de débogage et bonnes pratiques pour la destination ClickHouse de Fivetran.
# Dépannage et bonnes pratiques
## Erreurs courantes
### Le test des privilèges a échoué ou certaines opérations échouent en raison des autorisations
**Message d’erreur :**
```sh theme={null}
Test grants failed, cause: user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT
```
**Cause :** L’utilisateur Fivetran ne dispose pas des privilèges requis. Le connecteur nécessite les privilèges `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](/docs/fr/integrations/connectors/data-ingestion/etl-tools/fivetran/troubleshooting#role-based-grants) pour plus de détails.
**Solution :**
Accordez directement à l’utilisateur Fivetran les privilèges requis :
```sql theme={null}
GRANT CURRENT GRANTS ON *.* TO fivetran_user;
```
### Erreur lors de l’attente de l’achèvement de toutes les mutations
**Message d’erreur :**
```sh theme={null}
error while waiting for all mutations to be completed: ... initial cause: ...
```
**Cause :** Une mutation `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.
**Solutions :**
1. **Vérifier la progression de la mutation** : Exécutez la requête suivante pour rechercher d’éventuelles mutations en attente :
```sql theme={null}
SELECT database, table, mutation_id, command, create_time, is_done
FROM system.mutations
WHERE NOT is_done
ORDER BY create_time DESC;
```
2. **Vérifier l’état du cluster** : Assurez-vous que tous les nœuds sont en bon état.
3. **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
**Message d’erreur :**
Différentes erreurs peuvent survenir si la discordance des colonnes est due à une modification du schéma dans la source. Par exemple :
```sh theme={null}
columns count in ClickHouse table (8) does not match the input file (6). Expected columns: id, name, ..., got: id, name, ...
```
Ou :
```sh theme={null}
column user_email was not found in the table definition. Table columns: ...; input file columns: ...
```
**Cause :** Les colonnes de la table de destination ClickHouse ne correspondent pas à celles des données en cours de synchronisation. Cela peut se produire dans les cas suivants :
* 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.
**Solutions :**
1. **N’oubliez pas : ne modifiez pas manuellement les tables gérées par Fivetran.** Voir les [bonnes pratiques](/docs/fr/integrations/connectors/data-ingestion/etl-tools/fivetran/troubleshooting#dont-modify-tables).
2. **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](/docs/fr/integrations/connectors/data-ingestion/etl-tools/fivetran/reference#type-mapping).
3. **Relancez la synchronisation de la table** : Dans le tableau de bord Fivetran, déclenchez une resynchronisation historique pour la table concernée.
4. **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)
**Message d’erreur :**
```sh theme={null}
code: 168, message: AST is too big. Maximum: 50000
```
ou
```sh theme={null}
code: 62, message: Max query size exceeded
```
**Cause :** De gros lots d’UPDATE ou de DELETE génèrent des instructions SQL dotées d’arbres syntaxiques abstraits très complexes. C’est fréquent avec des tables comportant de nombreuses colonnes ou lorsque le mode historique est activé.
**Solution :**
Réduisez `mutation_batch_size` et `hard_delete_batch_size` dans le fichier de [configuration avancée](/docs/fr/integrations/connectors/data-ingestion/etl-tools/fivetran/reference#advanced-configuration). 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)
**Message d’erreur :**
```sh theme={null}
code: 241, message: (total) memory limit exceeded: would use 14.01 GiB
```
**Cause :** l’opération `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 :**
1. **Réduisez `write_batch_size`** : essayez de le ramener à 50 000 pour les grandes tables.
2. **Réduisez la charge de la base de données** : vérifiez la charge du service ClickHouse Cloud pour voir s’il est surchargé.
3. **Augmentez la capacité du service ClickHouse Cloud** pour disposer de plus de mémoire.
***
### EOF inattendue / Erreur de connexion
**Message d’erreur :**
```sh theme={null}
ClickHouse connection error: unexpected EOF
```
Ou `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.
**Solutions :**
1. **Vérifiez la liste d’accès IP** : dans ClickHouse Cloud, accédez à **Paramètres > Sécurité** et ajoutez les [adresses IP de Fivetran](https://fivetran.com/docs/using-fivetran/ips), ou autorisez l’accès depuis n’importe quelle adresse.
2. **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.
3. **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
**Message d’erreur :**
```sh theme={null}
cause: can't map type UInt64 to Fivetran types
```
**Cause :** Le connecteur associe `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 :**
1. **Ne modifiez pas manuellement les types de colonnes** dans les tables gérées par Fivetran.
2. **Pour corriger le problème** : rétablissez le type attendu pour la colonne (par exemple, `Int64`) ou supprimez puis resynchronisez la table.
3. **Pour les types personnalisés** : créez une [vue matérialisée](/docs/fr/reference/statements/create/view#materialized-view) sur la table gérée par Fivetran.
***
### Pas de clé primaire pour la table
**Message d’erreur :**
```sh theme={null}
Failed to alter table ... cause: no primary keys for table
```
**Cause :** Chaque table ClickHouse nécessite un `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 :**
1. **Contactez l’assistance Fivetran** pour examiner le pipeline source.
2. **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
**Message d’erreur :**
```sh theme={null}
user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT
```
**Cause :** Le connecteur vérifie les privilèges avec :
```sql theme={null}
SELECT access_type, database, table, column FROM system.grants WHERE user_name = 'my_user'
```
Cela ne renvoie que les privilèges accordés directement. Les privilèges attribués via un rôle ClickHouse ont `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 :
```sql theme={null}
GRANT CURRENT GRANTS ON *.* TO fivetran_user;
```
***
## Bonnes pratiques
### Service ClickHouse dédié à Fivetran
En cas de charge d’ingestion élevée, envisagez d’utiliser la fonctionnalité [compute-compute separation](/docs/fr/products/cloud/features/infrastructure/warehouses) de ClickHouse Cloud afin de créer un service dédié aux charges d’écriture de Fivetran. Cela permet d’isoler l’ingestion des requêtes analytiques et d’éviter les contentions de ressources.
Par exemple, l’architecture suivante peut être utilisée :
* **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
ClickHouse utilise `SharedReplacingMergeTree` pour les tables de destination Fivetran, qui est la version du [`moteur de table ReplacingMergeTree`](/docs/fr/concepts/features/operations/update/replacing-merge-tree) 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 :
```sql theme={null}
SELECT * FROM schema.table FINAL WHERE ...
```
Il existe plusieurs façons d’optimiser cette opération `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](/docs/fr/concepts/features/operations/update/replacing-merge-tree#final-performance) 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)`](/docs/fr/concepts/features/operations/insert/deduplication#avoiding-final).
* 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)`](https://clickhouse.com/blog/10-best-practice-tips#perfecting_replacingmergetree).
### Optimisation de la clé primaire et du `ORDER BY`
Fivetran réplique la clé primaire de la table source dans la clause ClickHouse `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](/docs/fr/guides/clickhouse/data-modelling/sparse-primary-indexes) à partir des colonnes de `ORDER BY`.
**Recommandations dans ce cas, si aucune autre optimisation n’est suffisante :**
1. **Traitez les tables Fivetran comme des tables de staging brutes.** Ne les interrogez pas directement à des fins analytiques.
2. **Si les requêtes ne sont toujours pas assez performantes**, utilisez une [vue matérialisée actualisable](/docs/fr/concepts/features/materialized-views/refreshable-materialized-view) pour créer une copie de la table avec un `ORDER BY` optimisé 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érations `UPDATE` et `DELETE` émises par Fivetran lors des synchronisations :
```sql theme={null}
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;
```
É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
Évitez les modifications DDL manuelles (par ex. `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](#uint64-type-error) et des incompatibilités de schéma.
Utilisez des vues matérialisées pour les transformations personnalisées.
## Débogage des opérations
En cas d’échec :
* Consultez le `system.query_log` de ClickHouse pour les problèmes côté serveur.
* Demandez de l’aide à Fivetran pour les problèmes côté client.
Pour les bogues du connecteur, [ouvrez une issue sur GitHub](https://github.com/ClickHouse/clickhouse-fivetran-destination/issues) ou contactez [ClickHouse Support](/docs/fr/resources/about/support).
### Débogage des synchronisations Fivetran
Utilisez les requêtes suivantes pour diagnostiquer les échecs de synchronisation du côté de ClickHouse.
#### Consulter les erreurs récentes de ClickHouse liées à Fivetran
```sql theme={null}
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;
```
#### Consulter l’activité récente des utilisateurs Fivetran
```sql theme={null}
SELECT event_time, query_kind, query, exception_code, exception
FROM system.query_log
WHERE user = '{fivetran_user}'
ORDER BY event_time DESC
LIMIT 100;
```