Skip to main content

よくあるエラー

権限の確認に失敗した、または権限に関連する操作が失敗している

エラーメッセージ:
原因: Fivetran ユーザーに必要な権限がありません。このコネクタでは、*.* (すべてのデータベースとテーブル) に対する ALTERCREATE DATABASECREATE TABLEINSERTSELECT の権限が必要です。
権限の確認では system.grants を照会し、ユーザーに直接付与された権限のみを判定します。ClickHouse のロールを通じて付与された権限は検出されません。詳細については、ロールベースの権限付与 セクションを参照してください。
解決策: 必要な権限を Fivetran ユーザーに直接付与します。

すべてのミューテーションの完了待機中に発生するエラー

エラーメッセージ:
原因: ALTER TABLE ... UPDATE または ALTER TABLE ... DELETE のミューテーションが送信されましたが、すべてのレプリカでの完了を待機している間に、コネクタがタイムアウトしました。エラーの「initial cause」部分には、元の ClickHouse エラー (多くの場合、コード 341 の「Unfinished」) が含まれていることがあります。 これは、次のような場合に発生することがあります。
  • ClickHouse Cloud クラスターに高い負荷がかかっている。
  • ミューテーションの実行中に 1 つ以上のノードがダウンした。
解決策:
  1. ミューテーションの進行状況を確認する: 保留中のミューテーションを確認するには、次のクエリを実行します。
  2. クラスターの状態を確認する: すべてのノードが正常であることを確認します。
  3. 待機して再試行する: クラスターが正常な状態に戻れば、ミューテーションは最終的に完了します。Fivetran は同期を自動的に再試行します。

カラムの不一致エラー

エラーメッセージ: ソース側のスキーマ変更によってカラムの不一致が生じている場合、さまざまなエラーが発生することがあります。たとえば、次のようなものです。
または:
原因: ClickHouse の宛先テーブルのカラムが、同期されるデータ内のカラムと一致していません。これは、次のような場合に発生することがあります。
  • ClickHouse テーブルにカラムが手動で追加または削除された。
  • ソース側のスキーマ変更が適切に反映されなかった。
解決策:
  1. Fivetran が管理するテーブルは手動で変更しないでください。 ベストプラクティスを参照してください。
  2. カラムを元に戻す: そのカラムが本来どの型であるべきか分かっている場合は、型変換マッピングを参考に、想定される型へカラムを変更し直してください。
  3. テーブルを再同期する: Fivetran のダッシュボードで、影響を受けたテーブルの履歴再同期を実行します。
  4. 削除して再作成する: 最後の手段として、宛先テーブルを削除し、次回の同期時に Fivetran に再作成させてください。

AST が大きすぎる (code 168)

エラーメッセージ:
または
原因: 大規模な UPDATE または DELETE のバッチによって、非常に複雑な抽象構文木を持つ SQL ステートメントが生成されます。列数の多いテーブルや History Mode が有効な場合によく発生します。 解決策: 高度な設定ファイルで、mutation_batch_sizehard_delete_batch_size の値を下げてください。どちらのデフォルト値も 1500 で、指定できる値の範囲は 200 から 1500 です。

メモリ上限超過 / OOM (code 241)

エラーメッセージ:
原因: INSERT 操作で、利用可能なメモリを超える量のメモリが必要になっています。通常は、大規模な初回同期、列数の多いテーブル、またはバッチ処理の同時実行時に発生します。 解決策:
  1. write_batch_size を減らす: 大きなテーブルでは、50,000 まで下げてみてください。
  2. データベースの負荷を下げる: ClickHouse Cloud サービスの負荷を確認し、過負荷になっていないか確認してください。
  3. ClickHouse Cloud サービスをスケールアップする: より多くのメモリを確保します。

予期しない EOF / 接続エラー

エラーメッセージ:
または、Fivetran のログにスタックトレースのない FAILURE_WITH_TASK が表示される。 原因:
  • Fivetran からのトラフィックを許可するように IP Access List が設定されていない。
  • Fivetran と ClickHouse Cloud 間で一時的なネットワーク障害が発生している。
  • 破損または無効なソースデータが原因で、宛先コネクタがクラッシュしている。
解決策:
  1. IP Access List を確認する: ClickHouse Cloud で Settings > Security に移動し、Fivetran の IP アドレスを追加するか、すべてのアクセスを許可します。
  2. 再試行する: 最近のコネクタバージョンでは、EOF エラーは自動的に再試行されます。散発的なエラー (1 日に 1~2 回) は、一時的なものである可能性が高いです。
  3. 問題が解消しない場合: エラーが発生した時間帯を添えて ClickHouse にサポートチケットを提出してください。あわせて、ソースデータの品質調査を Fivetran サポートにも依頼してください。

型 UInt64 をマッピングできません

エラーメッセージ:
原因: コネクタは LONGInt64 にマッピングし、UInt64 にはマッピングしません。このエラーは、Fivetran 管理下のテーブルでカラム型が手動で変更された場合に発生します。 解決策:
  1. Fivetran 管理下のテーブルでは、カラム型を手動で変更しないでください
  2. 復旧するには: カラムを想定される型 (例: Int64) に戻すか、テーブルを削除して再同期してください。
  3. カスタム型の場合: Fivetran 管理下のテーブルの上に materialized view を作成してください。

テーブルに主キーがない

エラーメッセージ:
原因: すべての ClickHouse テーブルには ORDER BY が必要です。ソースに主キーがない場合、Fivetran は自動的に _fivetran_id を追加します。このエラーは、まれに、ソースで PK が定義されているにもかかわらず、データにその PK が含まれていない場合に発生します。 解決策:
  1. Fivetran サポートに連絡して、ソースパイプラインを調査してもらってください。
  2. ソーススキーマを確認します: 主キーカラムがデータ内に存在することを確認してください。

ロールベースの権限付与が失敗する場合

エラーメッセージ:
原因: コネクタは次のように権限を確認します:
これは、直接付与された権限のみを返します。ClickHouse のロール経由で付与された権限は user_name = NULL かつ role_name = 'my_role' となるため、このチェックでは確認できません。 対処法: 権限を Fivetran ユーザーに直接付与します:

ベストプラクティス

Fivetran専用のClickHouseサービス

インジェスト負荷が高い場合は、ClickHouse Cloud の compute-compute separation を利用して、Fivetran の書き込みワークロード専用のサービスを作成することを検討してください。これにより、インジェスト処理を分析クエリから分離し、リソース競合を防ぐことができます。 たとえば、次のようなアーキテクチャを使用できます。
  • Service A (writer): Fivetran の宛先 + その他のインジェストツール (ClickPipes、Kafka コネクタ)
  • Service B (reader): BI ツール、ダッシュボード、アドホッククエリ

読み取りクエリの最適化

ClickHouse では、Fivetran の宛先テーブルに SharedReplacingMergeTree を使用します。これは、ClickHouse Cloud における ReplacingMergeTree テーブルエンジン のバージョンです。同じ主キーを持つ重複した行が存在するのは正常で、重複排除はバックグラウンドでのマージ中に非同期で行われます。読み取り時には、まだ重複排除されていない行が一部残っている可能性があるため、重複した行を返さないよう注意が必要です。 重複した行を避ける最も簡単な方法は FINAL キーワードを使うことです。これにより、まだ重複排除されていない行も、読み取り時に強制的にマージされます。
この FINAL 操作を最適化する方法はいくつかあります。たとえば、WHERE 条件でキーカラムを絞り込む方法です。詳しくは、ReplacingMergeTree ガイドの FINAL performance セクションを参照してください。 これらの最適化だけでは不十分な場合でも、重複を適切に処理しつつ FINAL を使わない方法がほかにもあります。

主キーとORDER BYの最適化

Fivetran は、ソーステーブルの主キーを ClickHouse の ORDER BY 句として複製します。ソースに PK がない場合、_fivetran_id (UUID) がソートキーになります。この場合、ClickHouse は ORDER BY カラムからスパースプライマリインデックスを構築するため、クエリパフォーマンスが低下する可能性があります。 他の最適化で十分な効果が得られない場合の推奨事項:
  1. Fivetran のテーブルは生のステージングテーブルとして扱ってください。 分析用途で直接クエリしないでください。
  2. それでもクエリパフォーマンスが不十分な場合はリフレッシュ可能なmaterialized viewを使用して、クエリパターンに合わせて ORDER BY を最適化したテーブルのコピーを作成してください。インクリメンタルmaterialized view とは異なり、リフレッシュ可能なmaterialized viewはスケジュールに従ってクエリ全体を再実行するため、Fivetran が同期中に実行する UPDATE および DELETE 操作を正しく処理できます。
Fivetran 管理下のテーブルでは、インクリメンタル (非リフレッシャブル) な materialized view の使用は避けてください。Fivetran はデータの同期を維持するために UPDATE および DELETE 操作を実行するため、インクリメンタルmaterialized view にはこれらの変更が反映されず、古いデータや不正確なデータが含まれてしまいます。

Fivetran が管理するテーブルを手動で変更しないでください

Fivetran が管理するテーブルに対して手動で DDL を変更すること (例: ALTER TABLE ... MODIFY COLUMN) は避けてください。コネクタは、自身が作成したスキーマを前提としています。手動で変更すると、型マッピングエラー やスキーマの不一致によるエラーが発生する可能性があります。 カスタム変換には materialized view を使用してください。

デバッグ

障害の原因を調査する際は、以下を確認してください。
  • サーバー側の問題は、ClickHouse の system.query_log を確認してください。
  • クライアント側の問題は、Fivetran にサポートを依頼してください。
コネクタのバグについては、GitHub issue を作成するか、ClickHouse Support にお問い合わせください。

Fivetran同期のデバッグ

以下のクエリを使用して、ClickHouse 側での同期失敗を診断します。

Fivetran に関連する ClickHouse の最近のエラーを確認する

Fivetranユーザーの最近のアクティビティを確認する

最終更新日 2026年7月3日