技術リファレンス

Fivetran の ClickHouse 宛先に関する型マッピング、テーブルエンジンの詳細、メタデータカラム、デバッグ用クエリ。

​

セットアップの詳細

​

ユーザーとロールの管理

default ユーザーの使用は避け、この Fivetran 宛先専用のユーザーを別途作成することをおすすめします。以下のコマンドを default ユーザーで実行すると、必要な権限を持つ新しい fivetran_user が作成されます。

CREATE USER fivetran_user IDENTIFIED BY '<password>'; -- 安全なパスワードジェネレーターを使用すること

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

さらに、fivetran_user の特定のデータベースへのアクセス権を取り消すこともできます。 たとえば、次のステートメントを実行すると、default データベースへのアクセスが制限されます。

REVOKE ALL ON default.* FROM fivetran_user;

ClickHouse SQL Console でこれらのステートメントを実行できます。

​

高度な設定

ClickHouse Cloud の宛先では、高度なユースケース向けにオプションの JSON 設定ファイルを使用できます。このファイルを使用すると、バッチサイズ、並列度、接続プール、リクエストタイムアウトを制御するデフォルト設定を上書きして、宛先の動作を細かく調整できます。

この設定は完全にオプションです。ファイルをアップロードしない場合、宛先ではほとんどのユースケースで適切に機能する妥当なデフォルト値が使用されます。

このファイルは有効な JSON であり、以下で説明するスキーマに準拠している必要があります。

初期設定後に構成を変更する必要がある場合は、Fivetran のダッシュボードで宛先の構成を編集し、更新したファイルをアップロードできます。

設定ファイルには、トップレベルのセクションがあります:

{
  "destination_configurations": { ... }
}

この中で、ClickHouse 宛先コネクタ自体の内部動作を制御する以下の設定を指定できます。 これらの設定は、コネクタが ClickHouse に送信する前にデータをどのように処理するかに影響します。

Setting	Type	Default	Allowed Range	Description
write_batch_size	integer	100000	5,000 – 100,000	insert、update、replace 操作で、1 バッチあたりに処理する行数。
select_batch_size	integer	1500	200 – 1,500	更新時に使用する SELECT クエリで、1 バッチあたりに処理する行数。
mutation_batch_size	integer	1500	200 – 1,500	History Mode での ALTER TABLE UPDATE mutation における、1 バッチあたりの行数。SQL ステートメントが大きくなりすぎる場合は、この値を下げてください。
hard_delete_batch_size	integer	1500	200 – 1,500	通常の同期および History Mode でのハード削除操作における、1 バッチあたりの行数。SQL ステートメントが大きくなりすぎる場合は、この値を下げてください。

すべてのフィールドは省略可能です。フィールドが指定されていない場合は、デフォルト値が使用されます。 値が許容範囲外の場合、宛先は同期中にエラーを報告します。 不明なフィールドは黙って無視され (警告はログに記録されます) 、エラーにはなりません。これにより、新しい設定が追加された場合でも前方互換性を確保できます。

例:

{
  "destination_configurations": {
    "write_batch_size": 50000,
    "select_batch_size": 200
  }
}

​

型変換マッピング

Fivetran の ClickHouse 宛先では、Fivetran のデータ型 を次のように ClickHouse の型にマッピングします。

Fivetran 型	ClickHouse 型
BOOLEAN	Bool
SHORT	Int16
INT	Int32
LONG	Int64
BIGDECIMAL	Decimal(P, S)
FLOAT	Float32
DOUBLE	Float64
LOCALDATE	Date32
LOCALDATETIME	DateTime64(0, ‘UTC’)
INSTANT	DateTime64(9, ‘UTC’)
STRING	String
LOCALTIME	String * **
BINARY	String *
XML	String *
JSON	String *

• BINARY、XML、LOCALTIME、JSON は、ClickHouse の String 型で任意のバイト列を表現できるため、String として保存されます。宛先では、元のデータ型を示すためにカラム comment が追加されます。ClickHouse の JSON データ型は、廃止されたものとされており、本番環境での使用は一度も推奨されていないため、使用されません。 ** 注: LOCALTIME 型のサポート状況を追跡する Issue: clickhouse-fivetran-destination #15。

​

日付および時刻の値の範囲

Fivetran のソースは、0001-01-01, 9999-12-31 の範囲の日付および時刻の値を送信できます。 ClickHouse Cloud の日付型はこれより対応範囲が狭いため、サポート範囲外の値は警告なしで最も近い境界値にクランプされます。

Fivetran type	ClickHouse Cloud type	Min value	Max value
LOCALDATE	Date32	1900-01-01	2299-12-31
LOCALDATETIME	DateTime64(0, ‘UTC’)	1900-01-01 00:00:00	2262-04-11 23:47:16
INSTANT	DateTime64(9, ‘UTC’)	1900-01-01 00:00:00	2262-04-11 23:47:16

• INSTANT の上限が 2262-04-11 23:47:16 である理由は、DateTime64(9) が epoch からのナノ秒を int64 として格納しており、2^63 - 1 ナノ秒がこの日時に相当するためです。 ClickHouse 自体は、精度 <= 9 の DateTime64 を 2299-12-31 23:59:59 までサポートしています。
• LOCALDATETIME の上限も、Go の ClickHouse ドライバーにある 既知のバグ により、2262-04-11 23:47:16 に制限されます。このバグでは、スケーリング前にすべての DateTime64 精度に対して time.Time.UnixNano() が呼び出されるため、精度 0 であっても 2262 年以降の日付で int64 overflow が発生します。

​

宛先テーブル

ClickHouse Cloud の宛先では、 SharedMergeTree ファミリーの Replacing エンジンタイプ (具体的には SharedReplacingMergeTree) を使用し、_fivetran_synced カラムでバージョン管理を行います。

プライマリ (並び順) キーおよび Fivetran のメタデータカラムを除くすべてのカラムは、 Nullable(T) として作成されます。ここで T は、 data types mapping に基づく ClickHouse Cloud のデータ型です。

テーブル構造は、コネクタに設定された Fivetran の sync mode (soft delete (デフォルト) または history mode (SCD Type 2) ) に応じて異なります。

​

ソフト削除モード

ソフト削除モードでは、すべての宛先テーブルに以下のメタデータカラムが含まれます。

カラム	型	説明
_fivetran_synced	DateTime64(9, 'UTC')	レコードが Fivetran によって同期されたタイムスタンプです。SharedReplacingMergeTree のバージョンカラムとして使用されます。
_fivetran_deleted	Bool	ソフト削除マーカーです。元のレコードが削除されると true に設定されます。
_fivetran_id	String	自動生成される一意の識別子です。ソーステーブルに主キーがない場合にのみ追加されます。

​

ソーステーブルに主キーが1つある場合

たとえば、ソーステーブル users には、主キーカラム id (INT) と通常のカラム name (STRING) があります。 宛先テーブルは次のように定義されます。

CREATE TABLE `users`
(
    `id`                Int32,
    `name`              Nullable(String),
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY id
SETTINGS index_granularity = 8192

この場合、id カラムがテーブルのソートキーとして選択されます。

​

ソーステーブルに複数の主キーがある場合

ソーステーブルに複数の主キーがある場合、それらは Fivetran のソーステーブル定義に 記載されている順に使用されます。

たとえば、ソーステーブル items に主キーカラム id (INT) と name (STRING) があり、さらに 通常のカラム description (STRING) があるとします。宛先テーブルは次のように定義されます。

CREATE TABLE `items`
(
    `id`                Int32,
    `name`              String,
    `description`       Nullable(String),
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, name)
SETTINGS index_granularity = 8192

この場合、id と name のカラムがテーブルのソートキーとして選択されます。

​

ソーステーブルに主キーがない場合

ソーステーブルに主キーがない場合、Fivetran によって一意の識別子が _fivetran_id カラムとして追加されます。 ソースの events テーブルに、event (STRING) と timestamp (LOCALDATETIME) のカラムしかない場合を考えてみましょう。 この場合の宛先テーブルは次のとおりです。

CREATE TABLE events
(
    `event`             Nullable(String),
    `timestamp`         Nullable(DateTime),
    `_fivetran_id`      String,
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY _fivetran_id
SETTINGS index_granularity = 8192

_fivetran_id は一意で、他に主キーの選択肢がないため、テーブルのソートキーに使用されます。

​

History mode (SCD Type 2)

History Mode が有効な場合、 宛先では以前の値を上書きせず、各レコードのすべてのバージョンを保持します。 これにより Slowly Changing Dimension Type 2 (SCD Type 2) が実装され、 すべての変更について完全な監査証跡が維持されます。

History Mode では、すべての宛先テーブルに次のメタデータカラムが含まれます。

カラム	Type	Description
_fivetran_synced	DateTime64(9, 'UTC')	レコードが Fivetran によって同期された時刻を示すタイムスタンプ。SharedReplacingMergeTree のバージョンカラムとして使用されます。
_fivetran_start	DateTime64(9, 'UTC')	このバージョンのレコードが有効になった時刻を示すタイムスタンプ。テーブルのソートキーの一部です。
_fivetran_end	Nullable(DateTime64(9, 'UTC'))	このバージョンが後続のバージョンに置き換えられた時刻を示すタイムスタンプ。現在有効なレコードでは 2262-04-11 23:47:16 に設定されます。
_fivetran_active	Nullable(Bool)	これが現在有効なレコードのバージョンかどうかを示します。
_fivetran_id	String	自動生成される一意の識別子。ソーステーブルに主キーがない場合にのみ存在します。

_fivetran_start カラムは、複合ソートキーの最後の要素として、常に ORDER BY 句に含まれます。 これにより、同じレコードの複数のバージョン (開始時刻が異なるもの) をテーブル内に共存させることができます。

レコードが更新されると、次のようになります。

• 以前のバージョンの _fivetran_end は、新しいバージョンの _fivetran_start から 1 ナノ秒引いた値に設定され、_fivetran_active は false に設定されます。
• 新しいバージョンは、_fivetran_active を true に、_fivetran_end を 2262-04-11 23:47:16.000000000 (DateTime64(9) の最大値) に設定して挿入されます。

​

ソーステーブルに単一の主キーがある場合

たとえば、ソーステーブル users には、主キーのカラム id (INT) と、通常のカラム name (STRING) および status (STRING) があります。 History Mode の宛先テーブルは次のように定義されます。

CREATE TABLE `users`
(
    `id`               Int32,
    `name`             Nullable(String),
    `status`           Nullable(String),
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, _fivetran_start)
SETTINGS index_granularity = 8192

この場合、id と _fivetran_start が複合ソートキーを構成します。

数回同期すると、テーブルには次のようなデータが含まれる可能性があります。

id	name	status	_fivetran_start	_fivetran_end	_fivetran_active
1	name 1	TODO	2025-11-10 20:57:00.000000000	2025-11-11 20:56:59.999000000	false
1	name 11	TODO	2025-11-11 20:57:00.000000000	2262-04-11 23:47:16.000000000	true
2	name 2	TODO	2025-11-10 20:57:00.000000000	2262-04-11 23:47:16.000000000	true

レコード id=1 には 2 つのバージョンがあります。元のもの (name 1、非アクティブ) と、更新後のもの (name 11、アクティブ) です。 レコード id=2 には 1 つのバージョンのみがあり、現在アクティブです。

​

ソーステーブルに複数の主キーがある場合

ソーステーブルに複数の主キーがある場合、それらはすべて、最後の要素である _fivetran_start とともに ORDER BY に含まれます。

たとえば、主キーカラム id (INT) と name (STRING) を持ち、さらに通常のカラム description (STRING) を持つソーステーブル items があるとします。History Mode の宛先テーブルは、次のように定義されます。

CREATE TABLE `items`
(
    `id`               Int32,
    `name`             String,
    `description`      Nullable(String),
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, name, _fivetran_start)
SETTINGS index_granularity = 8192

この場合、id、name、_fivetran_start が複合ソートキーとなります。

​

ソーステーブルに主キーがない場合

ソーステーブルに主キーがない場合、Fivetran によって一意の識別子が _fivetran_id カラムとして追加され、 _fivetran_start がソートキーに加えられます。 ソースに event (STRING) と timestamp (LOCALDATETIME) のカラムしかない events テーブルを考えてみましょう。 History Mode の宛先テーブルは以下のようになります。

CREATE TABLE events
(
    `event`            Nullable(String),
    `timestamp`        Nullable(DateTime),
    `_fivetran_id`     String,
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (_fivetran_id, _fivetran_start)
SETTINGS index_granularity = 8192

_fivetran_id と _fivetran_start が複合ソートキーを構成しているためです。

​

重複のないデータの最新バージョンを選択する

SharedReplacingMergeTree は、バックグラウンドでデータの重複排除を 不明なタイミングで実行される merge 中にのみ 行います。 ただし、FINAL キーワードを使うことで、その場で重複のないデータの最新バージョンを選択できます。

SELECT *
FROM example FINAL
LIMIT 1000 

クエリ最適化のヒントについては、トラブルシューティングガイドの読み取りクエリの最適化”セクションをご覧ください。

​

ネットワーク障害時の再試行

ClickHouse Cloud の宛先では、一時的なネットワークエラーに対して指数バックオフ アルゴリズムを使用して再試行を行います。 宛先側でデータが挿入される場合でも、重複の可能性は SharedReplacingMergeTree テーブルエンジンで処理されるため、安全です。