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

Рекомендуется не использовать пользователя 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.

Все поля необязательны. Если поле не указано, используется значение по умолчанию. Если значение выходит за пределы допустимого диапазона, коннектор назначения сообщит об ошибке во время синхронизации. Неизвестные поля игнорируются без уведомления (при этом в журнал записывается предупреждение) и не вызывают ошибок, что обеспечивает совместимость при добавлении новых настроек.

Пример:

{
  "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) хранит наносекунды с 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).

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

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

Когда режим истории включен, целевая система сохраняет каждую версию каждой записи вместо перезаписи предыдущих значений. Это реализует Slowly Changing Dimension Type 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 есть только одна версия, и сейчас она активна.

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