技术参考

建议不要使用 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 控制台中执行这些语句。

ClickHouse Cloud 目标端支持可选的 JSON 配置文件，以满足高级使用场景的需要。你可以通过此文件覆盖控制批次大小、并行度、连接池和请求超时的默认设置，从而微调目标端的行为。

该文件必须是有效的 JSON，并符合下文所述的 schema。

如果你需要在初始设置后修改配置，可以在 Fivetran dashboard 中编辑目标端配置并上传更新后的文件。

该配置文件包含一个顶层部分：

{
  "destination_configurations": { ... }
}

你可以在其中指定以下配置项，用于控制 ClickHouse 目标端连接器本身的内部行为。 这些配置会影响连接器在将数据发送到 ClickHouse 之前处理数据的方式。

所有字段均为可选项。若未指定某个字段，则使用默认值。 如果某个值超出允许范围，目标端会在同步期间报告错误。 未知字段会被静默忽略 (会记录一条警告日志) ，且不会导致错误，这样在新增设置时可保持前向兼容性。

示例：

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

Fivetran ClickHouse 目标端会按如下方式将 Fivetran 数据类型 映射为 ClickHouse 类型：

Fivetran 来源可以发送范围在 0001-01-01, 9999-12-31 内的日期和时间值。 ClickHouse Cloud 的日期类型支持范围更窄，因此超出支持范围的值会被静默限制到最近的边界值：

• INSTANT 的上限是 2262-04-11 23:47:16，因为 DateTime64(9) 将自纪元以来的纳秒存储为 int64，而 2^63 - 1 纳秒对应的正是这个日期。 ClickHouse 本身支持精度 <= 9 的 DateTime64，最高可达 2299-12-31 23:59:59。
• LOCALDATETIME 的上限同样受限于 2262-04-11 23:47:16，这是由于 Go ClickHouse 驱动中的一个已知 bug：在进行缩放之前，会对所有 DateTime64 精度调用 time.Time.UnixNano()，因此即使精度为 0，超过 2262 年的日期也会导致 int64 溢出。

ClickHouse Cloud 目标端采用 SharedMergeTree 家族的 Replacing 引擎类型 (具体来说是 SharedReplacingMergeTree) ，并以 _fivetran_synced 列作为版本列。

除主 (排序) 键和 Fivetran 元数据列外，每一列都会创建为 Nullable(T)，其中 T 是根据 数据类型映射确定的 ClickHouse Cloud 类型。

表结构会因连接器中配置的 Fivetran 同步模式 而异：软删除 (默认) 或 历史模式 (SCD Type 2) 。

在软删除模式下，每个目标表都包含以下元数据列：

例如，源表 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 具有唯一性，且没有其他主键可选，因此将其用作表的排序键。

启用历史模式后， 目标端会保留每条记录的所有版本，而不是覆盖之前的值。 这实现了缓慢变化维度 2 型 (SCD Type 2) ， 从而保留所有变更的完整审计轨迹。

在历史模式下，每个目标表都包含以下元数据列：

_fivetran_start 列始终作为复合排序键的最后一个元素包含在 ORDER BY 子句中。 这使同一条记录的多个版本 (开始时间不同) 能够在表中共存。

当记录更新时：

• 先前版本的 _fivetran_end 会被设置为新版本 _fivetran_start 减去一纳秒，同时 _fivetran_active 会被设置为 false。
• 新版本会被插入，其中 _fivetran_active 设为 true，_fivetran_end 设为 2262-04-11 23:47:16.000000000 (即 DateTime64(9) 的最大值) 。

例如，源表 users 有一个主键列 id (INT) ，以及普通列 name (STRING) 和 status (STRING) 。 历史模式下的目标表定义如下：

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=1 有两个版本：原始版本 (name 1，非活跃) 和更新后的版本 (name 11，活跃) 。 记录 id=2 只有一个版本，且当前为活跃状态。

如果源表有多个主键，这些主键都会与 _fivetran_start 一同包含在 ORDER BY 中，其中 _fivetran_start 位于最后。

例如，源表 items 的主键列为 id (INT) 和 name (STRING) ，此外还有一个 普通列 description (STRING) 。历史模式下的目标表定义如下：

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 追加到排序键中。 假设源中的 events 表只有 event (STRING) 和 timestamp (LOCALDATETIME) 两列。 历史模式下的目标表如下：

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 会在后台执行数据去重， 但仅会在不确定时间发生的合并过程中进行。 不过，也可以使用 FINAL 关键字临时查询去重后的最新数据版本：

SELECT *
FROM example FINAL
LIMIT 1000 

查看故障排除指南中的优化读取查询"一节，了解查询优化技巧。

ClickHouse Cloud 目标端会使用指数退避算法来重试临时性网络错误。 即使目标端已插入数据，这样做也是安全的，因为任何可能出现的重复数据都会由 SharedReplacingMergeTree 表引擎处理。