Если Kafka Engine читает одно событие несколько раз, в ClickHouse появляются дубли: метрики завышаются, отчеты расходятся, а бизнес перестает доверять аналитике.

Нужно понять, где возникает повтор: Kafka действительно хранит дубли, ClickHouse перечитывает offset или materialized view вставляет данные повторно после ошибки.

Коротко: что сделать

  • Проверить исходный topic на наличие дублей
  • Проверить consumer group Kafka Engine
  • Проверить логи ClickHouse по materialized view
  • Проверить commit offset и ошибки парсинга
  • Проверить схему дедупликации в целевой таблице

Основные причины

У проблемы может быть несколько уровней: интерфейс, backend, права, внешняя интеграция, кэш, очередь задач или настройки сервера. Поэтому лучше не гадать, а пройти цепочку от действия пользователя до записи в логах и базе.

  • Offset не коммитится из-за ошибки вставки
  • Materialized view падает на части сообщений
  • Consumer group была пересоздана или изменилась
  • В topic уже приходят дубли от источника
  • Целевая таблица не имеет дедупликации по event_id

Пошаговая диагностика

Диагностику удобнее вести на одном воспроизводимом примере: один пользователь, один заказ, один запрос, один файл или одно событие. Так проще отделить реальную причину от случайных совпадений.

  • Сравнить event_id дублей в ClickHouse
  • Проверить system.kafka_consumers и логи сервера
  • Проверить raw message в Kafka
  • Проверить ошибки парсинга JSON/Avro
  • Проверить настройки kafka_group_name и kafka_num_consumers

Как исправить проблему

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

  • Добавить event_id и дедупликацию в целевой слой
  • Исправить materialized view, чтобы она не падала на bad message
  • Настроить стабильную consumer group
  • Разделить raw и aggregated таблицы
  • Добавить мониторинг lag и ошибок Kafka Engine

Безопасный план решения

Не удаляйте дубли из боевой аналитики без понимания ключа события. Сначала сохраните raw-слой, определите правило уникальности и только затем пересчитайте агрегаты.

Чего не стоит делать

  • Не менять consumer group без плана
  • Не считать ClickHouse exactly-once системой без дедупликации
  • Не агрегировать без event_id или business key
  • Не игнорировать ошибки materialized view

Что подготовить перед исправлением

  • DDL Kafka Engine и materialized view
  • Пример event_id дубля
  • Логи ClickHouse
  • Настройки Kafka topic и consumer group
  • Целевая таблица

FAQ

Почему события читаются повторно после рестарта?

Если offset не был корректно зафиксирован, consumer может вернуться к уже прочитанным сообщениям.

Можно ли добиться exactly once?

На практике лучше проектировать идемпотентную загрузку и дедупликацию по event_id.

Где хранить raw события?

Отдельный raw-слой полезен для переобработки и проверки источника дублей.

Когда стоит обратиться за помощью

Помощь нужна, если отчеты, выручка, заказы или продуктовые метрики строятся на ClickHouse и Kafka.

Итог

Проверьте topic, offset, materialized view и дедупликацию по event_id. Если нужно убрать дубли в ClickHouse/Kafka, пишите в Telegram @rabotator_support.