Skip to main content

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

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

Сообщение об ошибке:
Причина: У пользователя Fivetran нет необходимых привилегий. Коннектору требуются привилегии ALTER, CREATE DATABASE, CREATE TABLE, INSERT и SELECT на *.* (во всех базах данных и таблицах).
При проверке привилегий выполняется запрос к system.grants, и учитываются только прямые привилегии пользователя. Привилегии, назначенные через роль ClickHouse, не обнаруживаются. Подробнее см. в разделе ролевые привилегии.
Решение: Предоставьте необходимые привилегии напрямую пользователю Fivetran:

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

Сообщение об ошибке:
Причина: Была отправлена мутация ALTER TABLE ... UPDATE или ALTER TABLE ... DELETE, но коннектор превысил время ожидания, пока она завершится на всех репликах. В части ошибки “initial cause” часто содержится исходная ошибка ClickHouse (обычно код 341, “Unfinished”). Это может произойти, если:
  • Кластер ClickHouse Cloud находится под высокой нагрузкой.
  • Один или несколько узлов вышли из строя во время выполнения мутации.
Решения:
  1. Проверьте ход выполнения мутации: Выполните следующий запрос, чтобы проверить наличие незавершенных мутаций:
  2. Проверьте состояние кластера: Убедитесь, что все узлы работают нормально.
  3. Подождите и повторите попытку: Мутации в конечном итоге завершаются, когда состояние кластера нормализуется. Fivetran автоматически повторит синхронизацию.

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

Сообщение об ошибке: Если несоответствие столбцов вызвано изменением схемы в источнике, могут возникать разные ошибки. Например:
Или:
Причина: Столбцы в целевой таблице ClickHouse не соответствуют столбцам в синхронизируемых данных. Это может произойти, если:
  • В таблицу ClickHouse вручную добавили или из неё удалили столбцы.
  • Изменение схемы в источнике не было корректно перенесено.
Решения:
  1. Не изменяйте вручную таблицы, которыми управляет Fivetran. См. рекомендации.
  2. Верните столбцу исходный тип: Если вы знаете, какой тип должен быть у столбца, измените его обратно на ожидаемый, используя сопоставление преобразований типов в качестве справочного материала.
  3. Повторно синхронизируйте таблицу: На панели мониторинга Fivetran запустите историческую повторную синхронизацию для затронутой таблицы.
  4. Удалите и создайте заново: В крайнем случае удалите целевую таблицу и позвольте Fivetran заново создать её при следующей синхронизации.

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

Сообщение об ошибке:
или
Причина: Большие батчи UPDATE или DELETE приводят к созданию SQL-операторов с очень сложными абстрактными синтаксическими деревьями. Это часто встречается при работе с широкими таблицами или при включенном режиме history mode. Решение: Уменьшите значения mutation_batch_size и hard_delete_batch_size в файле расширенной конфигурации. Для обоих параметров значение по умолчанию — 1500; допустимый диапазон — от 200 до 1500.

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

Сообщение об ошибке:
Причина: Операции INSERT требуется больше памяти, чем доступно. Обычно это происходит при крупных первичных синхронизациях, работе с широкими таблицами или параллельных батч-операциях. Решения:
  1. Уменьшите write_batch_size: Попробуйте снизить значение до 50 000 для больших таблиц.
  2. Уменьшите нагрузку на базу данных: Проверьте нагрузку на сервис ClickHouse Cloud, чтобы понять, не перегружен ли он.
  3. Масштабируйте сервис ClickHouse Cloud, чтобы увеличить объем доступной памяти.

Неожиданный 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

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

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

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

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

Сообщение об ошибке:
Причина: Коннектор проверяет привилегии так:
Это возвращает только прямые привилегии. Привилегии, назначенные через роль ClickHouse, имеют user_name = NULL и role_name = 'my_role', поэтому эта проверка их не учитывает. Решение: Назначьте привилегии напрямую пользователю Fivetran:

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

Выделенный сервис 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 — самый простой способ избежать дубликатов, поскольку оно принудительно выполняет слияние всех еще не дедуплицированных строк во время чтения:
Существуют способы оптимизировать эту операцию 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 выполняет во время синхронизации:
Избегайте 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

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

Последнее изменение 3 июля 2026 г.