Технический справочник

Сопоставление типов, сведения о движке таблицы, столбцах метаданных и запросах для отладки, связанных с пунктом назначения 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.

​

Расширенная конфигурация

Пункт назначения ClickHouse Cloud поддерживает необязательный JSON-файл конфигурации для расширенных сценариев использования. Этот файл позволяет тонко настроить поведение пункта назначения, переопределяя параметры по умолчанию, которые управляют размерами батчей, параллелизмом, пулами соединений и тайм-аутами запросов.

Эта конфигурация полностью необязательна. Если файл не загружен, пункт назначения использует подходящие параметры по умолчанию, которые хорошо работают в большинстве сценариев.

Файл должен быть корректным JSON и соответствовать схеме, описанной ниже.

Если вам нужно изменить конфигурацию после первоначальной настройки, вы можете отредактировать конфигурацию пункта назначения на панели мониторинга Fivetran и загрузить обновленный файл.

Файл конфигурации содержит раздел верхнего уровня:

{
  "destination_configurations": { ... }
}

В нём можно указать следующие параметры, которые управляют внутренним поведением самого коннектора назначения ClickHouse. Эти параметры влияют на то, как коннектор обрабатывает данные перед отправкой в ClickHouse.

Настройка	Тип	По умолчанию	Допустимый диапазон	Описание
write_batch_size	integer	100000	5,000 – 100,000	Число строк в батче для операций вставки, обновления и замены.
select_batch_size	integer	1500	200 – 1,500	Число строк в батче для запросов SELECT, используемых при обновлении.
mutation_batch_size	integer	1500	200 – 1,500	Число строк в батче для мутаций ALTER TABLE UPDATE в режиме истории. Уменьшите его, если SQL-операторы получаются слишком большими.
hard_delete_batch_size	integer	1500	200 – 1,500	Число строк в батче для операций жёсткого удаления при обычной синхронизации и в режиме истории. Уменьшите его, если 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 хранятся как String, поскольку тип String в ClickHouse может представлять произвольный набор байтов. Пункт назначения добавляет комментарий к столбцу, чтобы указать исходный тип данных. Тип данных JSON в ClickHouse не используется, так как он был помечен как устаревший и никогда не рекомендовался для использования в продакшн. ** ПРИМЕЧАНИЕ: Задача для отслеживания поддержки типа LOCALTIME: clickhouse-fivetran-destination #15.

​

Диапазоны значений даты и времени

Источники Fivetran могут отправлять значения даты и времени в диапазоне 0001-01-01, 9999-12-31. Типы даты и времени в ClickHouse Cloud имеют более узкие диапазоны, поэтому значения вне поддерживаемого диапазона без предупреждения приводятся к ближайшей границе:

Тип Fivetran	Тип ClickHouse Cloud	Минимальное значение	Максимальное значение
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 поддерживает DateTime64 с precision <= 9 вплоть до 2299-12-31 23:59:59.
• Верхняя граница для LOCALDATETIME также ограничена значением 2262-04-11 23:47:16 из-за известной ошибки в Go-драйвере ClickHouse: time.Time.UnixNano() вызывается для всех значений precision у DateTime64 до scaling, что приводит к overflow int64 для дат после 2262 года даже при precision 0.

​

Целевые таблицы

Для пункта назначения ClickHouse Cloud используется тип движка Replacing из семейства SharedMergeTree (в частности, SharedReplacingMergeTree) с версионированием по столбцу _fivetran_synced.

Каждый столбец, кроме первичных (сортировочных) ключей и столбцов метаданных Fivetran, создается как Nullable(T), где T — это тип ClickHouse Cloud на основе сопоставления типов данных.

Структура таблицы различается в зависимости от режима синхронизации, настроенного для коннектора: мягкое удаление (по умолчанию) или режим истории (SCD Type 2).

​

Режим мягкого удаления

В режиме мягкого удаления каждая целевая таблица содержит следующие служебные столбцы метаданных:

Столбец	Тип	Описание
_fivetran_synced	DateTime64(9, 'UTC')	Временная метка, указывающая, когда запись была синхронизирована Fivetran. Используется как столбец версии для SharedReplacingMergeTree.
_fivetran_deleted	Bool	Маркер мягкого удаления. Устанавливается в true, когда запись удаляется из источника.
_fivetran_id	String	Автоматически сгенерированный уникальный идентификатор. Присутствует только в том случае, если у исходной таблицы нет первичных ключей.

​

Один первичный ключ в исходной таблице

Например, исходная таблица 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 уникален и других вариантов первичного ключа нет, он используется в качестве ключа сортировки таблицы.

​

Режим истории (SCD Type 2)

Когда режим истории включен, целевая система сохраняет каждую версию каждой записи вместо перезаписи предыдущих значений. Это реализует Slowly Changing Dimension Type 2 (SCD Type 2), сохраняя полный аудитный след всех изменений.

В режиме истории каждая целевая таблица содержит следующие служебные столбцы метаданных:

Столбец	Тип	Описание
_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 новой версии минус одна наносекунда, а _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	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 есть две версии: исходная (name 1, неактивная) и обновлённая (name 11, активная). У записи id=2 есть только одна версия, и сейчас она активна.

​

Несколько первичных ключей в исходной таблице

Если в исходной таблице несколько первичных ключей, все они включаются в 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.