> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# 技術リファレンス

<div id="setup-details">
  ## セットアップの詳細
</div>

<div id="user-and-role-management">
  ### ユーザーとロールの管理
</div>

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

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

GRANT CURRENT GRANTS ON *.* TO fivetran_user;
```

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

```sql theme={null}
REVOKE ALL ON default.* FROM fivetran_user;
```

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

<div id="advanced-configuration">
  ### 高度な設定
</div>

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

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

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

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

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

```json theme={null}
{
  "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 ステートメントが大きくなりすぎる場合は、この値を下げてください。              |

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

例:

```json theme={null}
{
  "destination_configurations": {
    "write_batch_size": 50000,
    "select_batch_size": 200
  }
}
```

<div id="type-mapping">
  ## 型変換マッピング
</div>

Fivetran の ClickHouse 宛先では、[Fivetran のデータ型](https://fivetran.com/docs/destinations#datatypes) を次のように ClickHouse の型にマッピングします。

| Fivetran 型    | ClickHouse 型                                                |
| ------------- | ----------------------------------------------------------- |
| BOOLEAN       | [Bool](/ja/reference/data-types/boolean)                    |
| SHORT         | [Int16](/ja/reference/data-types/int-uint)                  |
| INT           | [Int32](/ja/reference/data-types/int-uint)                  |
| LONG          | [Int64](/ja/reference/data-types/int-uint)                  |
| BIGDECIMAL    | [Decimal(P, S)](/ja/reference/data-types/decimal)           |
| FLOAT         | [Float32](/ja/reference/data-types/float)                   |
| DOUBLE        | [Float64](/ja/reference/data-types/float)                   |
| LOCALDATE     | [Date32](/ja/reference/data-types/date32)                   |
| LOCALDATETIME | [DateTime64(0, 'UTC')](/ja/reference/data-types/datetime64) |
| INSTANT       | [DateTime64(9, 'UTC')](/ja/reference/data-types/datetime64) |
| STRING        | [String](/ja/reference/data-types/string)                   |
| LOCALTIME     | [String](/ja/reference/data-types/string) \* \*\*           |
| BINARY        | [String](/ja/reference/data-types/string) \*                |
| XML           | [String](/ja/reference/data-types/string) \*                |
| JSON          | [String](/ja/reference/data-types/string) \*                |

<Note>
  * BINARY、XML、LOCALTIME、JSON は、ClickHouse の `String` 型で任意のバイト列を表現できるため、[String](/ja/reference/data-types/string) として保存されます。宛先では、元のデータ型を示すためにカラム comment が追加されます。ClickHouse の [JSON](/ja/reference/data-types/newjson) データ型は、廃止されたものとされており、本番環境での使用は一度も推奨されていないため、使用されません。
    \*\* 注: LOCALTIME 型のサポート状況を追跡する Issue: [clickhouse-fivetran-destination #15](https://github.com/ClickHouse/clickhouse-fivetran-destination/issues/15)。
</Note>

<div id="date-and-time-value-ranges">
  ### 日付および時刻の値の範囲
</div>

Fivetran のソースは、[0001-01-01, 9999-12-31](https://fivetran.com/docs/destinations#dateandtimevaluerange) の範囲の日付および時刻の値を送信できます。
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 ドライバーにある [既知のバグ](https://github.com/ClickHouse/clickhouse-go/issues/1311) により、2262-04-11 23:47:16 に制限されます。このバグでは、スケーリング前にすべての DateTime64 精度に対して `time.Time.UnixNano()` が呼び出されるため、精度 0 であっても 2262 年以降の日付で int64 overflow が発生します。

<div id="table-structure">
  ## 宛先テーブル
</div>

ClickHouse Cloud の宛先では、
[SharedMergeTree](/ja/products/cloud/features/infrastructure/shared-merge-tree) ファミリーの
[Replacing](/ja/reference/engines/table-engines/mergetree-family/replacingmergetree) エンジンタイプ
(具体的には `SharedReplacingMergeTree`) を使用し、`_fivetran_synced` カラムでバージョン管理を行います。

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

テーブル構造は、コネクタに設定された Fivetran の
[sync mode](https://fivetran.com/docs/using-fivetran/features#deletedrowhandling)
(**soft delete** (デフォルト) または **history mode** (SCD Type 2) ) に応じて異なります。

<div id="soft-delete-mode">
  ### ソフト削除モード
</div>

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

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

<div id="single-pk">
  #### ソーステーブルに主キーが1つある場合
</div>

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

```sql theme={null}
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` カラムがテーブルのソートキーとして選択されます。

<div id="multiple-pks">
  #### ソーステーブルに複数の主キーがある場合
</div>

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

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

```sql theme={null}
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` のカラムがテーブルのソートキーとして選択されます。

<div id="no-pks">
  #### ソーステーブルに主キーがない場合
</div>

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

```sql theme={null}
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` は一意で、他に主キーの選択肢がないため、テーブルのソートキーに使用されます。

<div id="history-mode">
  ### History mode (SCD Type 2)
</div>

[History Mode](https://fivetran.com/docs/using-fivetran/features#historymode) が有効な場合、
宛先では以前の値を上書きせず、各レコードのすべてのバージョンを保持します。
これにより [Slowly Changing Dimension Type 2](https://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_2:_add_new_row) (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)` の最大値) に設定して挿入されます。

<div id="history-single-pk">
  #### ソーステーブルに単一の主キーがある場合
</div>

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

```sql theme={null}
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 つのバージョンのみがあり、現在アクティブです。

<div id="multiple-pks">
  #### ソーステーブルに複数の主キーがある場合
</div>

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

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

```sql theme={null}
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` が複合ソートキーとなります。

<div id="no-pks">
  #### ソーステーブルに主キーがない場合
</div>

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

```sql theme={null}
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` が複合ソートキーを構成しているためです。

<div id="selecting-latest-version">
  ### 重複のないデータの最新バージョンを選択する
</div>

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

```sql theme={null}
SELECT *
FROM example FINAL
LIMIT 1000 
```

クエリ最適化のヒントについては、トラブルシューティングガイドの[読み取りクエリの最適化](/ja/integrations/connectors/data-ingestion/etl-tools/fivetran/troubleshooting#optimizing-reading-queries)"セクションをご覧ください。

<div id="retries-on-network-failures">
  ## ネットワーク障害時の再試行
</div>

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