Перейти к основному содержанию

​
Распространённые ошибки

​
Сбой проверки привилегий или ошибки операций, связанные с разрешениями

Сообщение об ошибке: 
Test grants failed, cause: user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT
Причина: У пользователя Fivetran нет необходимых привилегий. Коннектору требуются привилегии ALTER, CREATE DATABASE, CREATE TABLE, INSERT и SELECT на *.* (во всех базах данных и таблицах).
При проверке привилегий выполняется запрос к system.grants, и учитываются только прямые привилегии пользователя. Привилегии, назначенные через роль ClickHouse, не обнаруживаются. Подробнее см. в разделе ролевые привилегии.
Решение: Предоставьте необходимые привилегии напрямую пользователю Fivetran: 
GRANT CURRENT GRANTS ON *.* TO fivetran_user;

​
Ошибка при ожидании завершения всех мутаций

Сообщение об ошибке: 
error while waiting for all mutations to be completed: ... initial cause: ...
Причина: Была отправлена мутация ALTER TABLE ... UPDATE или ALTER TABLE ... DELETE, но коннектор превысил время ожидания, пока она завершится на всех репликах. В части ошибки “initial cause” часто содержится исходная ошибка ClickHouse (обычно код 341, “Unfinished”). Это может произойти, если:
  • Кластер ClickHouse Cloud находится под высокой нагрузкой.
  • Один или несколько узлов вышли из строя во время выполнения мутации.
Решения:
  1. Проверьте ход выполнения мутации: Выполните следующий запрос, чтобы проверить наличие незавершенных мутаций: 
    SELECT database, table, mutation_id, command, create_time, is_done
FROM system.mutations
WHERE NOT is_done
ORDER BY create_time DESC;
  2. Проверьте состояние кластера: Убедитесь, что все узлы работают нормально.
  3. Подождите и повторите попытку: Мутации в конечном итоге завершаются, когда состояние кластера нормализуется. Fivetran автоматически повторит синхронизацию.

​
Ошибка несоответствия столбцов

Сообщение об ошибке: Если несоответствие столбцов вызвано изменением схемы в источнике, могут возникать разные ошибки. Например: 
columns count in ClickHouse table (8) does not match the input file (6). Expected columns: id, name, ..., got: id, name, ...
Или: 
column user_email was not found in the table definition. Table columns: ...; input file columns: ...
Причина: Столбцы в целевой таблице ClickHouse не соответствуют столбцам в синхронизируемых данных. Это может произойти, если:
  • В таблицу ClickHouse вручную добавили или из неё удалили столбцы.
  • Изменение схемы в источнике не было корректно перенесено.
Решения:
  1. Не изменяйте вручную таблицы, которыми управляет Fivetran. См. рекомендации.
  2. Верните столбцу исходный тип: Если вы знаете, какой тип должен быть у столбца, измените его обратно на ожидаемый, используя сопоставление преобразований типов в качестве справочного материала.
  3. Повторно синхронизируйте таблицу: На панели мониторинга Fivetran запустите историческую повторную синхронизацию для затронутой таблицы.
  4. Удалите и создайте заново: В крайнем случае удалите целевую таблицу и позвольте Fivetran заново создать её при следующей синхронизации.

​
Слишком большое AST (код 168)

Сообщение об ошибке: 
code: 168, message: AST is too big. Maximum: 50000
или 
code: 62, message: Max query size exceeded
Причина: Большие батчи UPDATE или DELETE приводят к созданию SQL-операторов с очень сложными абстрактными синтаксическими деревьями. Это часто встречается при работе с широкими таблицами или при включенном режиме history mode. Решение: Уменьшите значения mutation_batch_size и hard_delete_batch_size в файле расширенной конфигурации. Для обоих параметров значение по умолчанию — 1500; допустимый диапазон — от 200 до 1500.

​
Превышение лимита памяти / OOM (код 241)

Сообщение об ошибке: 
code: 241, message: (total) memory limit exceeded: would use 14.01 GiB
Причина: Операции INSERT требуется больше памяти, чем доступно. Обычно это происходит при крупных первичных синхронизациях, работе с широкими таблицами или параллельных батч-операциях. Решения:
  1. Уменьшите write_batch_size: Попробуйте снизить значение до 50 000 для больших таблиц.
  2. Уменьшите нагрузку на базу данных: Проверьте нагрузку на сервис ClickHouse Cloud, чтобы понять, не перегружен ли он.
  3. Масштабируйте сервис ClickHouse Cloud, чтобы увеличить объем доступной памяти.

​
Неожиданный EOF / Ошибка соединения

Сообщение об ошибке: 
ClickHouse connection error: unexpected EOF
Или FAILURE_WITH_TASK без трассировки стека в журналах Fivetran. Причины:
  • IP Access List не настроен для разрешения трафика Fivetran.
  • Временные проблемы с сетью между Fivetran и ClickHouse Cloud.
  • Поврежденные или некорректные исходные данные приводят к сбою коннектора назначения.
Решения:
  1. Проверьте IP Access List: в ClickHouse Cloud перейдите в Settings > Security и добавьте IP-адреса Fivetran или разрешите доступ откуда угодно.
  2. Повторите попытку: последние версии коннектора автоматически повторяют попытку при ошибках EOF. Редкие ошибки (1–2 в день), скорее всего, носят временный характер.
  3. Если проблема сохраняется: откройте тикет в поддержку ClickHouse, указав временной интервал возникновения ошибки. Также попросите поддержку Fivetran проверить качество исходных данных.

​
Не удаётся сопоставить тип UInt64

Сообщение об ошибке: 
cause: can't map type UInt64 to Fivetran types
Причина: Коннектор сопоставляет LONG с Int64, но не с UInt64. Эта ошибка возникает, если тип столбца вручную изменён в таблице, управляемой Fivetran. Решения:
  1. Не изменяйте типы столбцов вручную в таблицах, управляемых Fivetran.
  2. Чтобы восстановить состояние: измените тип столбца обратно на ожидаемый (например, Int64) или удалите таблицу и повторно синхронизируйте её.
  3. Для пользовательских типов: создайте materialized view поверх таблицы, управляемой Fivetran.

​
У таблицы нет первичного ключа

Сообщение об ошибке: 
Failed to alter table ... cause: no primary keys for table
Причина: Для каждой таблицы ClickHouse требуется ORDER BY. Если у источника нет первичного ключа, Fivetran автоматически добавляет _fivetran_id. Эта ошибка возникает в редких случаях, когда в источнике задан PK, но в данных он отсутствует. Решения:
  1. Обратитесь в поддержку Fivetran, чтобы проверить конвейер источника.
  2. Проверьте схему источника: убедитесь, что столбцы первичного ключа присутствуют в данных.

​
Не работают ролевые привилегии

Сообщение об ошибке: 
user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT
Причина: Коннектор проверяет привилегии так: 
SELECT access_type, database, table, column FROM system.grants WHERE user_name = 'my_user'
Это возвращает только прямые привилегии. Привилегии, назначенные через роль ClickHouse, имеют user_name = NULL и role_name = 'my_role', поэтому эта проверка их не учитывает. Решение: Назначьте привилегии напрямую пользователю Fivetran: 
GRANT CURRENT GRANTS ON *.* TO fivetran_user;

​
Рекомендации

​
Выделенный сервис ClickHouse для Fivetran

При высокой нагрузке на ингестию рассмотрите использование compute-compute separation в ClickHouse Cloud, чтобы создать выделенный сервис для нагрузок записи Fivetran. Это изолирует ингестию от аналитических запросов и предотвращает конкуренцию за ресурсы. Например, можно использовать следующую архитектуру:
  • Сервис A (writer): пункт назначения Fivetran + другие инструменты ингестии (ClickPipes, коннекторы Kafka)
  • Сервис B (reader): BI-инструменты, панели мониторинга, ad-hoc запросы

​
Оптимизация запросов на чтение

ClickHouse использует SharedReplacingMergeTree для целевых таблиц Fivetran — это версия движка таблицы ReplacingMergeTree в ClickHouse Cloud. Наличие строк-дубликатов с одинаковым первичным ключом — нормальное явление: дедупликация происходит асинхронно во время фоновых слияний. Поэтому при чтении данных нужно быть внимательными, чтобы не возвращать дубликаты, так как некоторые строки, возможно, еще не были дедуплицированы. Использование ключевого слова FINAL — самый простой способ избежать дубликатов, поскольку оно принудительно выполняет слияние всех еще не дедуплицированных строк во время чтения: 
SELECT * FROM schema.table FINAL WHERE ...
Существуют способы оптимизировать эту операцию FINAL — например, фильтровать по столбцам ключа с помощью условия WHERE. Подробнее см. в разделе производительность FINAL руководства по ReplacingMergeTree. Если этих оптимизаций недостаточно, есть и другие варианты, которые позволяют избежать использования FINAL, при этом по-прежнему корректно обрабатывать дубликаты:
  • Если нужно запрашивать числовой столбец, значение которого только растёт, можно использовать max(the_column).
  • Если нужно получить последнее значение в некоторых столбцах для конкретного ключа, можно использовать argMax(the_column, _fivetran_id).

​
Оптимизация первичного ключа и ORDER BY

Fivetran реплицирует первичный ключ исходной таблицы в выражение ClickHouse ORDER BY. Если у источника нет PK, ключом сортировки становится _fivetran_id (UUID), что может приводить к низкой производительности запросов, поскольку ClickHouse строит свой разреженный первичный индекс на основе столбцов ORDER BY. Рекомендации для таких случаев, если других оптимизаций недостаточно:
  1. Рассматривайте таблицы Fivetran как сырые staging-таблицы. Не используйте их напрямую для аналитических запросов.
  2. Если производительность запросов по-прежнему недостаточна, используйте Refreshable Materialized View, чтобы создать копию таблицы с ORDER BY, оптимизированным под ваши шаблоны запросов. В отличие от incremental materialized views, refreshable materialized views заново выполняют полный запрос по расписанию, что позволяет корректно обрабатывать операции UPDATE и DELETE, которые Fivetran выполняет во время синхронизации: 
    CREATE MATERIALIZED VIEW schema.table_optimized
REFRESH EVERY 1 HOUR
ENGINE = ReplacingMergeTree()
ORDER BY (user_id, event_date)
AS SELECT * FROM schema.table_raw FINAL;
Избегайте incremental (non-refreshable) materialized views для таблиц, которыми управляет Fivetran. Поскольку Fivetran выполняет операции UPDATE и DELETE для поддержания синхронизации данных, incremental materialized views не будут отражать эти изменения и будут содержать устаревшие или некорректные данные.

​
Не изменяйте таблицы, управляемые Fivetran, вручную

Избегайте ручных DDL-изменений (например, ALTER TABLE ... MODIFY COLUMN) в таблицах, которыми управляет Fivetran. Коннектор ожидает схему, которую создал сам. Ручные изменения могут вызывать ошибки сопоставления типов и сбои из-за несоответствия схемы. Используйте materialized views для пользовательских преобразований.

​
Отладка операций

При диагностике сбоев:
  • Проверьте system.query_log в ClickHouse на наличие проблем на стороне сервера.
  • По проблемам на стороне клиента обратитесь за помощью в Fivetran.
Если вы обнаружили ошибку в коннекторе, создайте issue на GitHub или свяжитесь с ClickHouse Support.

​
Отладка синхронизаций Fivetran

Используйте следующие запросы, чтобы диагностировать сбои синхронизации на стороне ClickHouse.

​
Проверьте недавние ошибки ClickHouse, связанные с Fivetran

SELECT event_time, query, exception_code, exception
FROM system.query_log
WHERE client_name LIKE 'fivetran-destination%'
  AND exception_code > 0
ORDER BY event_time DESC
LIMIT 50;

​
Просмотрите недавнюю активность пользователя Fivetran

SELECT event_time, query_kind, query, exception_code, exception
FROM system.query_log
WHERE user = '{fivetran_user}'
ORDER BY event_time DESC
LIMIT 100;
Последнее изменение 19 июня 2026 г.