よくあるエラー
権限の確認に失敗した、または権限に関連する操作が失敗している
*.* (すべてのデータベースとテーブル) に対する ALTER、CREATE DATABASE、CREATE TABLE、INSERT、SELECT の権限が必要です。
権限の確認では
system.grants を照会し、ユーザーに直接付与された権限のみを判定します。ClickHouse のロールを通じて付与された権限は検出されません。詳細については、ロールベースの権限付与 セクションを参照してください。すべてのミューテーションの完了待機中に発生するエラー
ALTER TABLE ... UPDATE または ALTER TABLE ... DELETE のミューテーションが送信されましたが、すべてのレプリカでの完了を待機している間に、コネクタがタイムアウトしました。エラーの「initial cause」部分には、元の ClickHouse エラー (多くの場合、コード 341 の「Unfinished」) が含まれていることがあります。
これは、次のような場合に発生することがあります。
- ClickHouse Cloud クラスターに高い負荷がかかっている。
- ミューテーションの実行中に 1 つ以上のノードがダウンした。
- ミューテーションの進行状況を確認する: 保留中のミューテーションを確認するには、次のクエリを実行します。
- クラスターの状態を確認する: すべてのノードが正常であることを確認します。
- 待機して再試行する: クラスターが正常な状態に戻れば、ミューテーションは最終的に完了します。Fivetran は同期を自動的に再試行します。
カラムの不一致エラー
- ClickHouse テーブルにカラムが手動で追加または削除された。
- ソース側のスキーマ変更が適切に反映されなかった。
- Fivetran が管理するテーブルは手動で変更しないでください。 ベストプラクティスを参照してください。
- カラムを元に戻す: そのカラムが本来どの型であるべきか分かっている場合は、型変換マッピングを参考に、想定される型へカラムを変更し直してください。
- テーブルを再同期する: Fivetran のダッシュボードで、影響を受けたテーブルの履歴再同期を実行します。
- 削除して再作成する: 最後の手段として、宛先テーブルを削除し、次回の同期時に Fivetran に再作成させてください。
AST が大きすぎる (code 168)
mutation_batch_size と hard_delete_batch_size の値を下げてください。どちらのデフォルト値も 1500 で、指定できる値の範囲は 200 から 1500 です。
メモリ上限超過 / OOM (code 241)
INSERT 操作で、利用可能なメモリを超える量のメモリが必要になっています。通常は、大規模な初回同期、列数の多いテーブル、またはバッチ処理の同時実行時に発生します。
解決策:
write_batch_sizeを減らす: 大きなテーブルでは、50,000 まで下げてみてください。- データベースの負荷を下げる: ClickHouse Cloud サービスの負荷を確認し、過負荷になっていないか確認してください。
- ClickHouse Cloud サービスをスケールアップする: より多くのメモリを確保します。
予期しない EOF / 接続エラー
FAILURE_WITH_TASK が表示される。
原因:
- Fivetran からのトラフィックを許可するように IP Access List が設定されていない。
- Fivetran と ClickHouse Cloud 間で一時的なネットワーク障害が発生している。
- 破損または無効なソースデータが原因で、宛先コネクタがクラッシュしている。
- IP Access List を確認する: ClickHouse Cloud で Settings > Security に移動し、Fivetran の IP アドレスを追加するか、すべてのアクセスを許可します。
- 再試行する: 最近のコネクタバージョンでは、EOF エラーは自動的に再試行されます。散発的なエラー (1 日に 1~2 回) は、一時的なものである可能性が高いです。
- 問題が解消しない場合: エラーが発生した時間帯を添えて ClickHouse にサポートチケットを提出してください。あわせて、ソースデータの品質調査を Fivetran サポートにも依頼してください。
型 UInt64 をマッピングできません
LONG を Int64 にマッピングし、UInt64 にはマッピングしません。このエラーは、Fivetran 管理下のテーブルでカラム型が手動で変更された場合に発生します。
解決策:
- Fivetran 管理下のテーブルでは、カラム型を手動で変更しないでください。
- 復旧するには: カラムを想定される型 (例:
Int64) に戻すか、テーブルを削除して再同期してください。 - カスタム型の場合: Fivetran 管理下のテーブルの上に materialized view を作成してください。
テーブルに主キーがない
ORDER BY が必要です。ソースに主キーがない場合、Fivetran は自動的に _fivetran_id を追加します。このエラーは、まれに、ソースで PK が定義されているにもかかわらず、データにその PK が含まれていない場合に発生します。
解決策:
- Fivetran サポートに連絡して、ソースパイプラインを調査してもらってください。
- ソーススキーマを確認します: 主キーカラムがデータ内に存在することを確認してください。
ロールベースの権限付与が失敗する場合
user_name = NULL かつ role_name = 'my_role' となるため、このチェックでは確認できません。
対処法:
権限を Fivetran ユーザーに直接付与します:
ベストプラクティス
Fivetran専用のClickHouseサービス
- Service A (writer): Fivetran の宛先 + その他のインジェストツール (ClickPipes、Kafka コネクタ)
- Service B (reader): BI ツール、ダッシュボード、アドホッククエリ
読み取りクエリの最適化
SharedReplacingMergeTree を使用します。これは、ClickHouse Cloud における ReplacingMergeTree テーブルエンジン のバージョンです。同じ主キーを持つ重複した行が存在するのは正常で、重複排除はバックグラウンドでのマージ中に非同期で行われます。読み取り時には、まだ重複排除されていない行が一部残っている可能性があるため、重複した行を返さないよう注意が必要です。
重複した行を避ける最も簡単な方法は FINAL キーワードを使うことです。これにより、まだ重複排除されていない行も、読み取り時に強制的にマージされます。
FINAL 操作を最適化する方法はいくつかあります。たとえば、WHERE 条件でキーカラムを絞り込む方法です。詳しくは、ReplacingMergeTree ガイドの FINAL performance セクションを参照してください。
これらの最適化だけでは不十分な場合でも、重複を適切に処理しつつ FINAL を使わない方法がほかにもあります。
- 常に増加する数値カラムをクエリする場合は、
max(the_column)を使用できます。 - 特定のキーに対して一部のカラムの最新の値を取得する必要がある場合は、
argMax(the_column, _fivetran_id)を使用できます。
Fivetran は、ソーステーブルの主キーを ClickHouse の
ORDER BY 句として複製します。ソースに PK がない場合、_fivetran_id (UUID) がソートキーになります。この場合、ClickHouse は ORDER BY カラムからスパースプライマリインデックスを構築するため、クエリパフォーマンスが低下する可能性があります。
他の最適化で十分な効果が得られない場合の推奨事項:
- Fivetran のテーブルは生のステージングテーブルとして扱ってください。 分析用途で直接クエリしないでください。
- それでもクエリパフォーマンスが不十分な場合は、リフレッシュ可能なmaterialized viewを使用して、クエリパターンに合わせて
ORDER BYを最適化したテーブルのコピーを作成してください。インクリメンタルmaterialized view とは異なり、リフレッシュ可能なmaterialized viewはスケジュールに従ってクエリ全体を再実行するため、Fivetran が同期中に実行するUPDATEおよびDELETE操作を正しく処理できます。
Fivetran 管理下のテーブルでは、インクリメンタル (非リフレッシャブル) な materialized view の使用は避けてください。Fivetran はデータの同期を維持するために
UPDATE および DELETE 操作を実行するため、インクリメンタルmaterialized view にはこれらの変更が反映されず、古いデータや不正確なデータが含まれてしまいます。Fivetran が管理するテーブルを手動で変更しないでください
ALTER TABLE ... MODIFY COLUMN) は避けてください。コネクタは、自身が作成したスキーマを前提としています。手動で変更すると、型マッピングエラー やスキーマの不一致によるエラーが発生する可能性があります。
カスタム変換には materialized view を使用してください。
デバッグ
- サーバー側の問題は、ClickHouse の
system.query_logを確認してください。 - クライアント側の問題は、Fivetran にサポートを依頼してください。