Если поток событий перестал загружаться после изменения JSON, сохраните безопасные примеры прежней и новой формы и найдите первое различие: имя поля, тип, обязательность или смысл значения. Не включайте пропуск любых ошибок на всём потоке. Начните с изолированной таблицы и искусственного события, по которому можно проверить каждое целевое поле.
Успешная вставка тоже требует проверки. Новое поле могло быть проигнорировано, а отсутствующее — получить значение по умолчанию, которое исказит отчёт. Нужный результат — объяснимое правило для каждой версии события и видимый учёт отклонённых записей, а не просто отсутствие красных сообщений у загрузчика.
Дополнительное поле и изменённая сумма — разные изменения
| Изменение события | Риск | Контрольный пример |
|---|---|---|
| Добавилось необязательное поле | Потерять полезную информацию при пропуске | Старый и новый parser читают общий набор |
| Число стало строкой | Неявное приведение или отказ | Число, числовой текст, нечисловой текст |
| Исчез обязательный статус | Ложное значение по умолчанию | Отсутствие отдельно от известного статуса |
| Сумма поменяла единицы | Формат принят, смысл неверен | Одно событие с известной величиной |
Для JSONEachRow документация ClickHouse описывает возможность пропускать неизвестные имена полей через input_format_skip_unknown_fields. Проверено 15 октября 2026 года. Это поведение относится к неизвестным полям, а не доказывает правильность новых типов или единиц измерения. Решение о допустимом пропуске принимается по контракту события; настройка не заменяет такой контракт.
Сначала договор отправителя и читателя
Если производитель может менять формат, введите различимую версию события либо другой согласованный признак контракта. Храните правила преобразования рядом с кодом загрузки. Версия должна описывать смысл, а не только дату выкладки: два разных отправителя могут некоторое время работать одновременно. При несовместимом изменении читатель сначала учится разбирать обе формы на стенде, затем разрешается выпуск нового отправителя.
Условный набор совместимости:
old_event -> old_reader: ожидаемый прежний результат
old_event -> new_reader: тот же смысл
new_event -> new_reader: новые согласованные поля
unknown_contract -> quarantine: без тихой подстановки
replay -> один предусмотренный бизнес-результатПромежуточный слой, сохраняющий исходное событие, помогает повторить преобразование после исправления, но требует ограниченного доступа и срока хранения. Не складывайте рабочие payload в открытые диагностические журналы. Для отклонения сохраняют безопасный идентификатор, причину и версию обработчика; доступ к исходным данным организуют отдельно.
Учитывайте подтверждение приёма: сообщение нельзя считать обработанным только потому, что parser дошёл до конца. Определите момент устойчивого сохранения результата или передачи в контролируемый карантин. Повтор после сбоя использует стабильную идентичность события, иначе исправленная загрузка может добавить дубли к уже принятым строкам.
Исправление reader не чинит прежний отчёт
- Зафиксировать диапазон времени и версии повреждённых событий.
- Отдельно измерить принятые, отклонённые и пропущенные поля.
- Испытать новый mapping на сохранённой безопасной выборке.
- Согласовать повторную обработку с учётом уже записанного результата.
- Сверить итоговые поля и агрегаты затронутого диапазона.
Откат старого reader допустим только пока он понимает события в очереди. Возврат кода без проверки оставшегося входа способен остановить загрузку повторно. Для технического разбора подготовьте версии отправителя и parser, обезличенные формы до и после, настройки формата и ожидаемую строку результата. Дальнейшее действие выбирают по конкретному несовместимому полю; массовое игнорирование исключений оставляет причину скрытой.