# ADR 0006. Имена объектов хранилища: суффикс вида

Дата: 4 августа 2026 года. Статус: принято.

## Решение

Имя объекта в ClickHouse заканчивается тем, что это за объект: `_rep` —
локальная таблица шарда, `_dist` — `Distributed` поверх неё, `_kafka` — чтец
топика, `_mv` — материализованное представление, `_v` — обычное представление.

Суффикс носит каждый физический объект, поэтому голого имени у таблицы не
существует: запрос к `stg.hits_raw` даёт ошибку «нет такой таблицы».
Единственное исключение — словари: воплощение у них одно, шардировать нечего, и
суффикс ничего не различал бы. В документах и разговоре голое имя означает
сущность, у которой этих объектов несколько.

Конвенция применена к мастер-спеке тем же решением: `stg.kafka_hits` стал
`stg.hits_raw_kafka`, `dds.v_event` — `dds.event_v`, витрины `dm.v_*` —
`dm.*_v`. Полная таблица суффиксов и следствия для DDL — в
[доке хранилища](../architecture/storage.md).

## Почему

Главный довод — как ошибается забытый суффикс. Распространённая конвенция, где
голое имя означает локальную таблицу, а распределённая получает `_all`,
ошибается молча: запрос к голому имени вернёт данные одного шарда и никак об
этом не скажет. Правило спеки «проверки и контрольные суммы — только по
`Distributed`» такую тишину не переживает: контрольная сумма, посчитанная по
половине кластера, выглядит как честное число. При суффиксе вида голого имени
нет вовсе, и та же ошибка становится громкой.

Второй довод — что группируется в `SHOW TABLES`. Суффикс группирует объекты по
сущности: все четыре объекта топика `hits` стоят рядом, потому что различаются
хвостом. Префиксный стиль, которым пользовался стенд-предшественник (`kafka_*`,
`mv_*`, `v_*`), группирует по технологии, и объекты одной сущности
расползаются по алфавиту. В хранилище, где у одной сущности живёт по три-четыре
воплощения, полезнее первое.

Третий — преемственность: `_rep` и `_dist` уже используются владельцем в других
хранилищах на ClickHouse, и общий словарь между стендами стоит больше, чем
локальная стройность.

Отвергнуты, кроме `_all`: префиксный стиль предшественника — он не покрывает
пару локальная/распределённая, для неё префикса просто нет; голое имя как
`Distributed` с суффиксом `_local` у локальной — привычное имя ведёт в
правильную таблицу, но конвенция расходится с другими стендами владельца;
раскладка пары по разным базам (`stg` и `stg_dist`) — удваивает число баз в
каждом слое и разъезжается с таблицей слоёв спеки.

Цена решения — правка принятой спеки задним числом. Имена представлений и
витрин переехали с префикса на суффикс, хотя сами объекты спроектированы не
полностью и появятся только на этапах 4 и дальше. Размен принят осознанно:
конвенция, введённая после того, как по ней написан первый слой, обходится
дороже.

## Что проверено

Проверять здесь нечем — это соглашение, а не поведение системы. Вместо проверки
конвенция прогнана по карте таблиц спеки, раздел 7: суффикс выводится для всех
объектов слоёв STG, ODS, DDS и DM, включая пары локальная/распределённая,
представления и матвью. Единственным объектом без выводимого суффикса оказался
словарь `products` — отсюда исключение в решении.