From 45360b6bcf422b65e6a63f374f197b317c965f64 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sat, 22 Aug 2026 04:35:41 -0400 Subject: [PATCH] =?UTF-8?q?docs(ods):=20=D0=B2=D1=8B=D1=87=D0=B8=D1=82?= =?UTF-8?q?=D0=B0=D0=BD=D1=8B=20=D0=BA=D0=BE=D0=BC=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=80=D0=B8=D0=B8=20=D0=B8=20=D0=B4=D0=BE=D0=BA=D1=83?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BF=D0=BE?= =?UTF-8?q?=D1=87=D0=B8=D0=BD=D0=BA=D0=B8=20=D1=80=D0=B0=D1=81=D0=BA=D0=BB?= =?UTF-8?q?=D0=B0=D0=B4=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - правки #137 дважды рассказывали одно и то же: механика капкана жила и в storage.md, и у вставок, а цифры замеров — и в прозе, и в леджере; у читателя это спрашивает больше внимания, чем даёт. - Что: - комментарии у вставок order_parse.sql сжаты до довода с указателем на storage.md; из капкана в storage.md цифры ушли в «Что проверено»; в ingestion.md замеры перенесены из прозы в свой раздел «Что проверено». - Проверка: - рендер order_parse.sql по-прежнему делится ровно на два запроса (из комментария убрана точка с запятой, по которой оператор делит файл). Co-Authored-By: Claude Opus 5 (1M context) --- docs/architecture/orders/ingestion.md | 36 ++++++++++++++------------- docs/architecture/storage.md | 22 ++++++++-------- sql/ods/order_parse.sql | 19 ++++++-------- 3 files changed, 36 insertions(+), 41 deletions(-) diff --git a/docs/architecture/orders/ingestion.md b/docs/architecture/orders/ingestion.md index 1a612e3..39b9e5a 100644 --- a/docs/architecture/orders/ingestion.md +++ b/docs/architecture/orders/ingestion.md @@ -106,24 +106,19 @@ JSON-объектом с точным набором ключей: `order_id`, ` - `_load_id` — какой запуск Airflow принял строку; - `_load_ts` — когда строка приехала в хранилище. -У выжившей после схлопывания строки три последние координаты означают меньше, -чем кажется. Версию выбирает только `updated_at`; заказ, не менявшийся -несколько дней, приезжает в нескольких слепках одинаковыми деловыми полями, и -какая из этих строк переживёт схлопывание — не обещано. Поэтому её -`snapshot_date` — *один из* дней, когда источник показывал эту версию, не -обязательно последний; то же с `_load_id` и `_load_ts`. Замер 22 августа -2026 года (#137): у 86 заказов стартового мира выжил даже не крайний день, а -серединный. Вопрос «когда заказ наблюдался в последний раз» задаётся сырью STG, -пока его не съел срок жизни, — а не одной строке ODS. +Версию выбирает только `updated_at`. Заказ, не менявшийся несколько дней, +приезжает в нескольких слепках одинаковыми деловыми полями, и какая из этих +строк переживёт схлопывание — не обещано. Поэтому `snapshot_date` выжившей +строки — один из дней, когда источник показывал эту версию, не обязательно +последний; то же с `_load_id` и `_load_ts`. Вопрос «когда заказ наблюдался в +последний раз» задаётся сырью STG, пока то живо, — а не одной строке ODS. -Вся схема версий стоит на одном свойстве источника: уточнение заказа поднимает -`updated_at`. Наш генератор моделирует источник с триггерной меткой и это -свойство гарантирует; замеры 22 августа 2026 года его подтвердили — во всех -парах строк с равным `updated_at` деловые поля совпали побайтово, а по слепкам -метка не убывала ни разу. Это допущение, а не закон природы: источник, умеющий -уточнить строку тихо — правка мимо приложения, миграция, ручной `UPDATE`, — -эту схему ломает, и тогда версии по метке времени уже не хватает, нужна сверка -самих полей (в терминах dbt snapshots — стратегия `check` вместо `timestamp`). +Сама схема версий стоит на допущении об источнике: уточнение заказа поднимает +`updated_at`. Генератор моделирует источник с триггерной меткой и допущение +выполняет (замер — «Что проверено»); источник, умеющий уточнить строку тихо — +ручным `UPDATE` мимо приложения, миграцией, — ломает его, и тогда версии по +метке времени мало: нужна сверка самих полей, в терминах dbt snapshots — +стратегия `check` вместо `timestamp`. Обычное чтение `_dist` показывает физически сохранившиеся версии и нужно для диагностики. Их число зависит от фоновых слияний: ODS не служит архивом истории. @@ -205,6 +200,13 @@ JSON-объектом с точным набором ключей: `order_id`, ` `system.query_log` на первой ноде осталось ровно по одному завершённому запросу пользователя `etl` для забора в STG, записи годных строк и записи брака. +Допущение и произвол ярлыков замерены 22 августа 2026 года при исполнении +#137: во всех 3034 парах строк с равным `updated_at` деловые поля совпали +побайтово, по слепкам метка ни разу не убывала, а `ods.order_v` сошёлся +построчно с эталоном `argMax` по `updated_at`, посчитанным прямо из сырья. +Произвол ярлыков виден въявь: у 86 заказов стартового мира выжила строка +серединного слепка — не первого и не последнего. + Забор из Kafka в STG снят на живом стенде 18 августа 2026 года при исполнении #93: одно прямое чтение приносит весь слепок дня, метаданные доставки доступны, офсеты коммитятся, а сбой забора не двигает позицию мира. Числа — [ADR diff --git a/docs/architecture/storage.md b/docs/architecture/storage.md index afca243..1ab42e9 100644 --- a/docs/architecture/storage.md +++ b/docs/architecture/storage.md @@ -87,15 +87,14 @@ CSV-файла. Живёт он вне цепочки слоёв, в зоне `d Разные ключи у слоёв ставят капкан на вставке `INSERT INTO цель_dist SELECT … FROM источник_dist`. Заводское значение `parallel_distributed_insert_select` — 2: если обе таблицы на одном кластере, вставка исполняется локально на каждом -шарде, и шард пишет прямо в локальную таблицу цели, минуя её ключ шардирования. -Строки наследуют раскладку источника, и ошибки при этом нет: расхождение видно -только пересчётом по `hostName()` — сколько ключей встретилось больше чем на -одном шарде. На разборе заказов так и вышло: 1189 из 1662 заказов легли -одинаковыми строками на оба шарда, а `ReplacingMergeTree` через границу шарда их -не схлопывает. Поэтому у такой вставки в `SETTINGS` стоит явное -`parallel_distributed_insert_select = 0`: раскладку делает инициатор, по ключу -цели (`sql/ods/order_parse.sql`). Правило нужно и дальше — сборки DDS тоже будут -читать `_dist` и писать в `_dist` с другим ключом. +шарде, минуя ключ шардирования цели. Строки наследуют раскладку источника, и +ошибки при этом нет — расхождение видно только пересчётом ключей по +`hostName()`. Так половина заказов и легла на оба шарда, где +`ReplacingMergeTree` через границу шарда дубли не схлопывает (замер — «Что +проверено», #137). Лекарство — явное `parallel_distributed_insert_select = 0` +в `SETTINGS` такой вставки: раскладку делает инициатор, по ключу цели +(`sql/ods/order_parse.sql`). Капкан ждёт и сборки DDS: они тоже будут читать +`_dist` и писать в `_dist` с другим ключом. Ключи ко-локации названы заранее, потому что на них стоит политика соединений из раздела 6 спеки: обычное соединение разрешено только по ключу ко-локации, всё @@ -592,9 +591,8 @@ DDL-словарь с файловым источником внутри `user_f на каждом шарде, `2` — `SELECT` и `INSERT` на каждом шарде; заводское — `2`. На живых данных видны и дефект, и починка: до правки 1189 из 1662 заказов лежали на обоих шардах, после явного нуля и повторного разбора того же -`_load_id` — ни одного, каждый шард держит только свои ключи. Вершина версий -уцелела: деловые поля `ods.order_v` сошлись с эталоном, посчитанным прямо из -сырья. +`_load_id` — ни одного. Вершина версий уцелела: деловые поля `ods.order_v` +сошлись с эталоном, посчитанным прямо из сырья. **Проверка версий заказов 18 августа 2026 года (#94).** MCP Context7 подтвердил, что `JSONType` возвращает имя типа значения JSON, — на нём стоит проверка типов diff --git a/sql/ods/order_parse.sql b/sql/ods/order_parse.sql index e54c9e6..2b757f1 100644 --- a/sql/ods/order_parse.sql +++ b/sql/ods/order_parse.sql @@ -92,14 +92,11 @@ SELECT _load_ts FROM stg.orders_raw_dist WHERE _load_id = {load_id:String} AND row_is_valid --- Заводское значение parallel_distributed_insert_select — 2: вставку вида --- INSERT ... SELECT из Distributed в Distributed на одном кластере ClickHouse --- исполняет локально на каждом шарде, и строки минуют ключ шардирования цели. --- Ключи здесь разные — сырьё разложено по хешу строки, заказы по --- cityHash64(order_id), — так версии одного заказа и расползлись по обоим --- шардам, где ReplacingMergeTree их уже не схлопывает. Ноль возвращает вставку --- инициатору: он читает срез со всех шардов и пишет через ods.order_dist, --- то есть по её ключу. +-- Заводская двойка parallel_distributed_insert_select исполняет вставку из +-- Distributed в Distributed локально на каждом шарде, минуя ключ шардирования +-- цели, — так заказы и расползлись по обоим шардам. Ноль отдаёт раскладку +-- инициатору, по ключу цели. Капкан целиком — docs/architecture/storage.md, +-- «Раскладка по шардам». SETTINGS distributed_foreground_insert = 1, parallel_distributed_insert_select = 0; @@ -127,9 +124,7 @@ SELECT _load_ts FROM stg.orders_raw_dist WHERE _load_id = {load_id:String} AND NOT row_is_valid --- Тот же ноль, хотя здесь заводское значение раскладку не ломало: ключ у --- ods.order_errors_dist — cityHash64(raw), тот же, что у сырья, и локальная --- запись попадала бы в свой шард сама. Совпадение ключей не гарантия: --- поменяется ключ любой из двух таблиц — и строки разъедутся молча. +-- Тот же ноль: ключ брака сегодня совпадает с ключом сырья, и локальная +-- запись легла бы верно — но по совпадению, а не по контракту. SETTINGS distributed_foreground_insert = 1, parallel_distributed_insert_select = 0;