ddadminandClaude Opus 5
5cc0ede75a
Зачем: ревью в три линии нашло настоящий дефект. Девятая проверка кластера
звала dictGet('dds.products', …) — объекта после переноса не существует, и
make check-clickhouse падал. Промах вырос из недосчёта: упоминания dds.products
я искал с фильтром по расширениям, .sh туда не попал, и в ADR уехало «четыре
упоминания» вместо семи.
Что: проверка переведена на dic.products и сверяет цену, умножив её обратно на
сто, — так утверждается ещё и точность приведения к Decimal. Раздел 3
мастер-спеки и список пользователей README догнали перенос: оба описывали
отменённое устройство. В ADR 0012 добавлено условие пересмотра для дома — для
него его не было, хотя ради дома тикет и заводился; недосчёт записан в
«Что проверено» как урок. Разнобой обозначений сведён: карта таблиц в доке
хранилища перешла на имена баз строчными, таблица мастер-спеки — на заголовок
«Где», зону всюду зовут зоной, а не слоем. Термин «Справочник» переписан без
метафоры и уложен в формат глоссария. Вычтено лишнее: комментарии DDL
сократились вдвое, из ADR 0006 и 0007 убраны самооправдание и дублирующие
абзацы, отраслевой образец получил честную оговорку о непроверяемости.
Проверка: make config-test, make lint, make smoke и make check-clickhouse —
все зелёные, десять проверок кластера из десяти.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6.3 KiB
ADR 0006. Имена объектов хранилища: суффикс вида
Дата: 4 августа 2026 года. Статус: принято.
Решение
Имя объекта в ClickHouse заканчивается тем, что это за объект: _rep —
локальная таблица шарда, _dist — Distributed поверх неё, _kafka — чтец
топика, _file — чтец файла, _mv — материализованное представление, _v —
обычное представление.
Суффикс _file пришёл с подложкой под словарём товаров
(ADR 0012).
Суффикс носит каждый физический объект, поэтому голого имени у таблицы не
существует: запрос к stg.hits_raw даёт ошибку «нет такой таблицы».
Единственное исключение — словари: воплощение у них одно, шардировать нечего, и
суффикс ничего не различал бы. В документах и разговоре голое имя означает
сущность, у которой этих объектов несколько.
Конвенция применена к мастер-спеке тем же решением: stg.kafka_hits стал
stg.hits_raw_kafka, dds.v_event — dds.event_v, витрины dm.v_* —
dm.*_v. Полная таблица суффиксов и следствия для DDL — в
доке хранилища.
Почему
Главный довод — как ошибается забытый суффикс. Распространённая конвенция, где
голое имя означает локальную таблицу, а распределённая получает _all,
ошибается молча: запрос к голому имени вернёт данные одного шарда и никак об
этом не скажет. Правило спеки «проверки и контрольные суммы — только по
Distributed» такую тишину не переживает: контрольная сумма, посчитанная по
половине кластера, выглядит как честное число. При суффиксе вида голого имени
нет вовсе, и та же ошибка становится громкой.
Второй довод — что группируется в списке по алфавиту. Суффикс группирует объекты
по сущности: все четыре объекта топика hits стоят рядом, потому что различаются
хвостом. Префиксный стиль, которым пользовался стенд-предшественник (kafka_*,
mv_*, v_*), группирует по технологии, и объекты одной сущности
расползаются по алфавиту. В хранилище, где у одной сущности живёт по три-четыре
воплощения, полезнее первое. Довод про дерево в клиенте и про ORDER BY name:
порядок выдачи SHOW TABLES документация не оговаривает, так что на него здесь
опираться нельзя.
Третий — преемственность: _rep и _dist уже используются владельцем в других
хранилищах на ClickHouse, и общий словарь между стендами стоит больше, чем
локальная стройность.
Отвергнуты, кроме _all: префиксный стиль предшественника — он не покрывает
пару локальная/распределённая, для неё префикса просто нет; голое имя как
Distributed с суффиксом _local у локальной — привычное имя ведёт в
правильную таблицу, но конвенция расходится с другими стендами владельца;
раскладка пары по разным базам (stg и stg_dist) — удваивает число баз в
каждом слое и разъезжается с таблицей слоёв спеки.
Цена решения — правка принятой спеки задним числом. Имена представлений и витрин переехали с префикса на суффикс, хотя сами объекты спроектированы не полностью и появятся только на этапах 4 и дальше. Размен принят осознанно: конвенция, введённая после того, как по ней написан первый слой, обходится дороже.
Что проверено
Проверять здесь нечем — это соглашение, а не поведение системы. Вместо проверки
конвенция прогнана по карте таблиц спеки, раздел 7: суффикс выводится для всех
объектов слоёв STG, ODS, DDS и DM, включая пары локальная/распределённая,
представления и матвью. Единственным объектом без выводимого суффикса оказался
словарь products — отсюда исключение в решении.
Первый прогон был неполным: четыре витрины из восьми остались с префиксом, и заметило это холодное ревью, а не автор. Имена приведены в порядок 5 августа 2026 года. Урок не про имена: «прогнал по документу» — такое же утверждение, как утверждение о поведении системы, и проверять его надо так же.