После добавления колонки загрузчик может продолжить отправлять прежний набор значений без явного списка целевых полей. Тогда вставка зависит от количества и порядка колонок таблицы. Сначала сохраните схему тестовой таблицы до и после изменения и фактическую форму запроса отправителя. Не повторяйте рабочий импорт, пока не ясно, какие записи уже приняты.
Проверьте также перенос через выборку всех полей: расширение источника меняет её состав. Безопасный тест — старый отправитель и новая схема на искусственных строках с различимыми значениями каждого поля. Ожидается не просто успешный ответ, а попадание каждого значения в свою колонку. Совместимые типы могут скрыть перестановку.
Карта полей должна существовать вне порядка таблицы
Условный контракт отправителя:
source_field_a -> target_field_a
source_field_b -> target_field_b
new_target_field -> <согласованное значение или default>
writer_revision: <версия загрузчика>
schema_revision: <проверенная схема>Документация ClickHouse позволяет указать явный список колонок вставки. Для вставки результата выборки соответствие колонок определяется позицией, а имена выражений могут отличаться от целевых. Если часть колонок пропущена в явном списке, используются предусмотренные значения по умолчанию. Проверено 14 октября 2026 года. Поэтому имена и порядок на обеих сторонах договора проверяются совместно.
| Симптом | Где смотреть | Что проверить |
|---|---|---|
| Изменилось число ожидаемых значений | Форма вставки | Есть ли явный список колонок |
| Ошибки типов после расширения | Позиционное сопоставление | Не сдвинулись ли поля |
| Запрос успешен, значения неверны | Прочитанная тестовая строка | Не обменялись ли совместимые типы |
| Сбой только на части узлов | Фактическая схема адресата | Все ли нужные изменения дошли |
Значение по умолчанию должно иметь смысл
Ноль или пустая строка технически могут позволить старому отправителю продолжить работу, но бизнес-смысл нового поля остаётся вопросом. Если поле обозначает подтверждённое состояние, отсутствие сведений нельзя незаметно объявить подтверждением. Опишите поведение старой записи, нового отправителя и периода совместного существования версий.
Проверяйте реальную цель записи: приложение может писать через промежуточную таблицу, представление или другой маршрут, чем ручной тест. Сравните имя базы, таблицу и используемый формат без вывода секретных параметров соединения. Исправленный запрос к одной тестовой таблице не доказывает исправление всей цепочки.
Явный список не решает несовместимость типов или исчезнувшее поле. Он делает контракт заметным и ограничивает зависимость от чужих изменений. На следующем выпуске проверяйте отправителей, потребителей и фактическое чтение нового поля. Прежний код может успешно писать, но ошибаться при разборе расширенного ответа по позициям.
Приёмка запускает старую и новую версии рядом
- Старый отправитель на расширенной схеме.
- Новый отправитель с заполненным новым полем.
- Отсутствующее поле и согласованный default.
- Различимые значения соседних одинаковых типов.
- Повтор отклонённой загрузки после проверки прежнего исхода.
Если данные уже попали не в те колонки, изменение запроса защищает только будущие вставки. Найдите затронутый период и восстановите значения из достоверного источника отдельной процедурой. Не удаляйте новый столбец как универсальный откат: он может уже содержать нужные данные нового отправителя. Для разбора достаточно обеих схем, версии writer и искусственной строки, у которой видно назначение каждого значения.