На старте аналитического проекта список показателей обычно уже существует. Он находится в техническом задании, таблице заказчика, старых отчётах или переписке. В нём могут быть знакомые названия: количество пользователей, доля выполнения, среднее значение, динамика по подразделениям.

Кажется, что этого достаточно, чтобы подключить данные и начать собирать дашборд. Проблема обнаруживается позже, когда участники проекта по-разному понимают один и тот же показатель. Для одного активный пользователь - любой открывший приложение, для другого - успешно авторизовавшийся, для третьего - совершивший целевое действие. Формула появляется только после того, как одна из трактовок незаметно побеждает остальные.

В проектах с BI-отчётностью я работал с показателями, которые собирались из внутренних систем, общей базы, API и ручных выгрузок. При проектировании аналитики мобильного приложения похожая задача возникла ещё до накопления данных: нужно было определить активность, возвращаемость, использование экранов, ключевые действия и ошибки. В обоих случаях название показателя было лишь началом работы.

Словарь метрик позволяет зафиксировать эту работу до первого дашборда. Но для этого он должен быть не списком терминов и не приложением к техническому заданию, а управляемым реестром определений, владельцев, источников, ограничений и версий.

Таблица показателей ещё не является словарём

Простейший список часто содержит три столбца: название, формула и источник. Он помогает собрать требования, но не обеспечивает воспроизводимость.

Предположим, записано:

Формально описание есть. На практике остаются вопросы:

• какое действие делает пользователя активным;

• считается человек, аккаунт, устройство или установка;

• как объединяется активность до и после авторизации;

• за какой период определяется уникальность;

• какой часовой пояс задаёт границу суток;

• включаются ли тестовые и служебные аккаунты;

• что происходит с событиями, пришедшими с задержкой;

• когда период считается полным;

• кто имеет право изменить определение;

• какие отчёты используют эту метрику.

Если ответы хранятся только в коде конкретного отчёта, каждое новое представление может получить собственную версию показателя. Если они остаются в переписке, то теряются при смене участников проекта. Если их знает один аналитик, система зависит от его памяти.

Словарь начинается там, где по записи можно не только понять название, но и воспроизвести смысл расчёта, проверить его и оценить последствия изменения.

Проблема не в формуле, а в договорённостях

Большинство споров о показателях выглядит технически: какой фильтр применить, по какой дате группировать, использовать COUNT или COUNT DISTINCT. Но за каждым таким вопросом находится бизнес-договорённость.

Например, показатель «выполненные операции» может относиться к операциям, завершённым внутри периода, или к операциям, которые находятся в завершённом состоянии на отчётную дату. Первый вариант измеряет поток событий, второй - состояние набора объектов. SQL будет разным, потому что разным является сам вопрос.

То же относится к исключениям. Удалённые, тестовые, отменённые или неполные записи можно исключить из расчёта, но это решение меняет границы наблюдаемого процесса. Оно должно быть согласовано до реализации и одинаково применяться во всех отчётах.

В BI-кейсе с сопоставлением подразделений было недостаточно вывести доступные значения. Нужно было определить, какие объекты можно сравнивать, по какой методике, за один ли период сформированы данные и не объясняется ли различие масштабом подразделений. Часть этой информации фиксировалась при сборе требований и проверке отчёта. Словарь метрик позволяет вынести её в отдельный повторно используемый слой.

Главная ценность словаря в том, что он разделяет два решения:

• что именно организация считает показателем;

• как это определение реализовано в данных и коде.

Первое нельзя незаметно менять при редактировании запроса. Второе нельзя отрывать от согласованного смысла.

Что должен знать словарь о метрике

Одна запись должна описывать не только вычисление, но и контекст использования. Я бы разделил её на несколько связанных блоков.

Не каждое поле обязательно заполнять в первый день. Но структура должна заставлять команду увидеть пробелы до того, как они превратятся в неявные решения разработчика.

Особенно важен уникальный идентификатор. Отображаемое название может измениться, получить сокращение или перевод. Стабильный код вроде product.active_accounts.daily позволяет связать определение с моделью данных, тестами, API и дашбордами без зависимости от подписи на экране.

Минимальная запись, с которой уже можно работать

Для первого варианта словаря не нужна отдельная платформа. Достаточно согласованного шаблона, доступного аналитикам, разработчикам и владельцам процесса.

Практический минимум выглядит так:

Такой шаблон шире карточки показателя, которая обычно используется при сборе требований. Разница в том, что словарь хранит связи между записями, жизненный цикл и техническое использование. Он должен продолжать работать после завершения первого дашборда.

Пример: активная аудитория мобильного приложения

При проектировании аналитики мобильного приложения я закладывал активных и новых пользователей, DAU, WAU, MAU, сессии, возвращаемость, просмотры экранов, ключевые действия и ошибки. Фактические значения и эффект внедрения здесь не рассматриваются: подтверждённым результатом был план измерений до полноценного накопления данных.

Этот пример хорошо показывает, почему словарь нужен заранее. Запись «DAU - уникальные активные пользователи за день» почти ничего не определяет. В качестве иллюстрации её можно оформить так:

id: product.active_accounts.daily
name: Активные аккаунты за день
aliases:
  - DAU
status: approved
version: 2

meaning:
  definition: Уникальные авторизованные аккаунты, совершившие хотя бы одно учитываемое действие в течение календарного дня
  purpose: Оценка охвата реального использования основных функций продукта

calculation:
  entity: account_id
  inclusion_event_set: approved_activity_events
  aggregation: count_distinct
  unit: accounts
  grain: calendar_day
  time_field: event_occurred_at
  timezone: agreed_business_timezone
  exclusions:
    - test_accounts
    - events_without_valid_account_id

data:
  canonical_source: validated_product_events
  refresh: daily
  late_data_policy: recalculate_open_period

governance:
  owner: product_owner
  technical_owner: analytics_team
  effective_from: approval_date
  restatement_policy: documented

Это не описание реально внедрённой конфигурации конкретной системы, а пример структуры на основе спроектированного набора аналитики.

Даже в нём остаётся отдельный объект - approved_activity_events. Если набор учитываемых действий записать внутри каждого отчёта, определение снова раздвоится. Значит, словарь должен уметь ссылаться не только на показатели, но и на управляемые наборы событий, статусов, сегментов и исключений.

Например, открытие технического экрана может не означать полезную активность, а событие успешного действия нельзя отправлять до подтверждения результата. Повторное нажатие может создать несколько клиентских событий. Эти правила относятся не к визуализации DAU, а к контракту аналитического события и подготовке канонического набора данных.

Метрики образуют систему, а не плоский список

В обычной таблице каждая строка выглядит независимой. В реальном аналитическом контуре показатели связаны.

Относительная метрика зависит от числителя и знаменателя. Динамика зависит от базового показателя и правила сопоставления периодов. Конверсия связывает начальное и целевое события, сущность и допустимое окно. Показатель качества ограничивает возможность интерпретации основной метрики.

Поэтому в словаре полезно выделять типы связей:

• derived_from - показатель вычисляется из других метрик;

• numerator_of и denominator_of - участие в относительном показателе;

• guardrail_for - ограничитель для интерпретации результата;

• quality_check_for - показатель качества исходных данных;

• replaces - новая версия или определение заменяет устаревшее;

• consumed_by - использование в отчёте, выгрузке, API или управленческом процессе.

Так плоский список превращается в граф зависимостей. Он отвечает не только на вопрос «как считается показатель», но и на вопрос «что изменится, если его определение поменять».

Современные семантические слои используют похожую идею на уровне исполнения. Например, в актуальной документации dbt семантические модели описываются как узлы графа, связанные сущностями; отдельно задаются временные и категориальные измерения, ключи и метрики. Простые метрики могут служить основой для относительных, производных, накопительных и конверсионных. Практически важен сам принцип: связи и допустимые способы расчёта описываются один раз, а не собираются заново внутри каждого отчёта. Это можно проверить в документации dbt Semantic Models и dbt Metrics.

Словарь не обязан сразу выполнять запросы, но его модель лучше проектировать так, чтобы позднее определения можно было перенести в семантический слой без полной переработки.

Разрезы тоже являются частью определения

В дашборде фильтр или группировка часто воспринимаются как свободная настройка представления. Но не каждую метрику можно корректно разложить по любому доступному справочнику.

Например, уникальных пользователей нельзя получить суммированием distinct count по устройствам, если один аккаунт использует несколько устройств. Показатель состояния на отчётную дату нельзя без дополнительного правила группировать по подразделению из текущего справочника, если объект мог переходить между подразделениями. При соединении метрики с категорией «многие ко многим» одна сущность может попасть сразу в несколько групп.

Поэтому в словаре полезно хранить не просто перечень красивых фильтров, а совместимость метрики с измерениями:

Такая матрица помогает отделить три ситуации: разрез безопасен, разрез требует специальной агрегации или разрез вообще меняет смысл показателя.

В более развитой реализации рядом с измерением хранится допустимый путь соединения. Семантический слой может сам построить JOIN, но словарь должен заранее определить, почему эта связь корректна и какая кардинальность ожидается. Иначе автоматизация лишь ускорит получение правдоподобного, но неверного результата.

Отдельно стоит фиксировать, где метрика аддитивна. Сумму операций можно складывать по периодам и подразделениям, если категории не пересекаются. Остаток на дату обычно можно суммировать по подразделениям, но нельзя складывать по дням. Доли, медианы и уникальные сущности требуют пересчёта на целевой гранулярности.

Таким образом, запись в словаре отвечает не только на вопрос «как получить число», но и на вопрос «какие преобразования с этим числом остаются корректными».

Статус показывает, можно ли доверять определению

Наличие записи в словаре ещё не означает, что показатель разрешено использовать в опубликованной отчётности.

Для начала достаточно трёх статусов:

• draft - определение обсуждается, источники или правила ещё могут измениться;

• approved - смысл, реализация и проверки согласованы, метрика разрешена для использования;

• deprecated - показатель сохранён для истории, но не должен подключаться к новым отчётам.

Переход из draft в approved должен означать не просто заполнение строки. Перед утверждением нужно проверить, что существует владелец, доступен источник, однозначно определена сущность, воспроизводится формула, описана временная логика и есть хотя бы один способ сверки.

Для deprecated требуется ссылка на замену или объяснение, почему метрика больше не используется. Иначе пользователи продолжат находить её в старых отчётах и воспринимать как действующую.

Статус полезно показывать прямо в инструментах потребления. Если экспериментальная метрика доступна только в тестовом разделе, это должно быть видно. Скрывать неопределённость за обычной карточкой опаснее, чем временно не публиковать показатель.

Версия нужна даже при неизменной формуле

Метрика может измениться без редактирования арифметики. Источник добавил новый статус, справочник начал иначе классифицировать объекты, изменился набор учитываемых событий или правило объединения идентификаторов.

Поэтому версионировать нужно определение целиком, а не только текст формулы.

Новая версия должна фиксировать:

• дату вступления в силу;

• причину изменения;

• автора и согласовавшего владельца;

• изменённые поля контракта;

• влияние на исторические значения;

• зависимые отчёты и показатели;

• решение о перерасчёте прошлого.

Для истории возможны три режима. Новое определение применяется ко всему сопоставимому периоду, начинает действовать только с указанной даты или некоторое время рассчитывается параллельно со старым. Выбор зависит от назначения метрики и доступности исходных данных.

Особенно важно отделять изменение процесса от изменения метода измерения. Если на графике показатель вырос после перехода на новую версию, пользователь должен понимать, где реальное изменение, а где разрыв методики.

Я бы хранил у каждой записи поля effective_from, effective_to и restatement_policy. Тогда система может ответить, какое определение действовало на дату публикации и была ли история пересчитана позже.

Документ и код не должны расходиться

У словаря есть типичная точка отказа: аналитик обновляет формулу в модели, а описание остаётся прежним. Через несколько месяцев документ выглядит подробным, но больше не отражает расчёт.

Чтобы этого избежать, полезно разделить поля на три группы.

Бизнес-поля согласуются человеком: смысл, назначение, владелец, область применения и ограничения.

Технические поля по возможности формируются из кода или проверяются автоматически: источник, выражение, зависимости, временное поле, доступные измерения и версия модели.

Операционные поля вычисляются самой системой: дата последнего успешного расчёта, свежесть, результат тестов, фактические потребители и статус публикации.

Если всё поддерживается вручную, словарь быстро устаревает. Если всё генерируется из SQL, он теряет бизнес-смысл. Рабочий вариант сочетает ручное согласование семантики с автоматическим получением технических метаданных.

Для небольшого проекта это можно реализовать без сложной платформы:

• хранить записи в Markdown или YAML рядом с аналитическим кодом;

• проверять обязательные поля при изменении;

• связывать ID метрики с представлением или моделью данных;

• генерировать человекочитаемую таблицу из файлов;

• запрещать изменение утверждённой метрики без новой версии;

• хранить историю через систему контроля версий.

Так появляется подход metrics as code: определение становится частью процесса разработки, проходит проверку и выпускается вместе с изменением расчёта.

Что проверять автоматически

Словарь приносит пользу, когда его записи можно валидировать. Само наличие подробного описания не гарантирует согласованность.

На уровне структуры я бы проверял уникальность ID, обязательность владельца, версии и статуса, корректность ссылок на источники и отсутствие циклов в зависимостях. У устаревшей метрики должна быть причина вывода из использования, а у замены - ссылка на предыдущую запись.

На уровне данных нужны тесты, связанные со смыслом:

• уникальность ключа на заявленной гранулярности;

• допустимость значений статусов;

• отсутствие неожиданных пропусков в сущности и временном поле;

• соответствие числителя и знаменателя;

• сохранение аддитивности там, где она заявлена;

• полнота периода и свежесть источника;

• сверка детализации с общим итогом.

На уровне изменений полезен semantic diff - сравнение двух версий не как текста файла, а как набора значимых полей. Изменение описания можно выпустить без перерасчёта, а изменение популяции, временного поля, ключа или исключений должно запускать проверку исторического влияния.

Термин semantic diff здесь обозначает практический метод сравнения контрактов. Это не ссылка на отдельный обязательный стандарт.

Проверка может сформировать отчёт:

Изменено: inclusion_event_set
Предыдущая версия: 2
Новая версия: 3
Затронутые метрики: 4
Затронутые отчёты: 3
Исторический пересчёт: требуется решение владельца
Регрессионные тесты: пройдены

Числа в этом примере условные. В реальном контуре они должны вычисляться по графу зависимостей, а не заполняться вручную.

У определения и данных разные состояния

Статус approved говорит, что методика согласована. Он не означает, что сегодняшнее значение уже рассчитано, источник полностью обновился, а проверки качества прошли успешно.

Если смешать эти понятия в одном поле, утверждённая метрика будет выглядеть надёжной даже во время сбоя загрузки. Обратная ситуация тоже возможна: временная проблема данных переведёт корректное определение обратно в черновик.

Поэтому я бы разделял как минимум два состояния:

• definition_status - жизненный цикл определения: draft, approved, deprecated;

• data_status - состояние последнего расчёта: healthy, delayed, incomplete, failed.

Рядом можно показывать время последнего успешного обновления, максимальную дату события, результат обязательных тестов и долю полученных источников. Это превращает словарь в точку диагностики: пользователь видит не только формулу, но и может ли сейчас доверять конкретному значению.

Для основной метрики полезно определить условия готовности. Например, значение публикуется только после поступления всех обязательных источников, прохождения проверки уникальности и закрытия согласованного окна поздних данных. Эти условия являются частью контракта публикации.

Здесь важно не перегружать бизнес-пользователя техническими журналами. В интерфейсе достаточно понятного статуса и времени актуальности. Детальные результаты тестов нужны аналитикам и разработчикам, которые расследуют отклонение.

Так словарь связывает два уровня управления: согласованность смысла и наблюдаемость исполнения. Первый защищает от разных трактовок, второй - от использования правильной метрики на неполных данных.

Как собрать словарь до первого дашборда

Начинать лучше не со всех терминов организации, а с границ конкретного аналитического продукта. Для дашборда сравнения подразделений это основные результаты, показатели масштаба, динамика, ориентиры, качество данных и используемые разрезы. Для мобильного продукта - аудитория, сессии, возвращаемость, экраны, действия и ошибки.

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

Затем для каждой метрики формулируется определение без названий таблиц и полей. Если смысл невозможно объяснить простым предложением, техническая формула пока преждевременна.

После этого фиксируются сущность, событие включения, временная логика и исключения. Именно здесь обычно обнаруживается, что один показатель распадается на несколько: состояние на дату, события за период и накопительный итог.

Только затем определение связывается с источником и прототипом расчёта. Если нужные данные не хранятся, метрика остаётся в статусе draft с явным ограничением. Нельзя делать её approved только потому, что в дашборде уже подготовлено место.

Перед публикацией полезно провести короткую проверку на сценарии. Будущий пользователь получает название, определение и несколько примеров пограничных записей. Он должен определить, входят ли они в расчёт и почему. Разработчик отдельно воспроизводит результат по тем же правилам. Если трактовки расходятся, словарь ещё не готов.

Первый дашборд после этого становится потребителем утверждённых метрик. Он выбирает представление и нужные разрезы, но не переопределяет основную логику внутри визуализации.

Где хранить словарь

Единственного правильного инструмента нет. Выбор зависит от размера контура и зрелости процесса.

На практике эти варианты могут дополнять друг друга. YAML хранит исполняемую часть, каталог показывает владельцев и связи, семантический слой рассчитывает метрики, а BI-инструмент отображает результат.

Контракты данных решают соседнюю задачу: фиксируют ожидания между производителем и потребителем набора данных. В актуальном Open Data Contract Standard предусмотрены разделы для схемы, качества, ролей, SLA и инфраструктуры. Такой контракт не заменяет словарь метрик, потому что не определяет управленческий смысл каждого показателя. Но он помогает защитить расчёт от незаметного изменения входных данных.

Чего словарь не исправляет

Словарь не делает плохие данные качественными. Если источник не хранит историю, не передаёт нужное событие или содержит дубли, подробное определение только зафиксирует ограничение.

Он не заменяет владельца. Команда аналитики может предложить формулу, но не должна самостоятельно решать, какие бизнес-состояния считать успешными, если от этого зависит управленческая оценка.

Он не гарантирует единство, если отчёты могут обходить утверждённые определения. Для общих показателей нужны технические ограничения или хотя бы автоматическая проверка соответствия словарю.

Он не должен превращаться в энциклопедию всех возможных терминов. Если запись не связана с решением, источником или потребителем, её актуальность невозможно проверить.

Наконец, словарь не является разовым результатом этапа требований. После запуска дашборда появляются новые исключения, источники и сценарии. Если изменения не проходят через версии и владельцев, документ снова превращается в архив первоначальных договорённостей.

Чек-лист готовности словаря

Перед использованием метрики в первом дашборде я бы проверил:

1. Есть ли у метрики стабильный ID?

2. Понятно ли определение без чтения SQL?

3. Указано ли решение, которое она поддерживает?

4. Определены ли сущность и событие включения?

5. Зафиксированы ли популяция, исключения и единица измерения?

6. Описаны ли временное поле, период, гранулярность и часовой пояс?

7. Понятно ли, как учитывать поздние данные и исправления?

8. Указаны ли допустимые разрезы и правила агрегации?

9. Есть ли канонический источник и способ сверки?

10. Назначены ли бизнес-владелец и технический владелец?

11. Перечислены ли зависимые метрики и потребители?

12. Есть ли статус draft, approved или deprecated?

13. Зафиксированы ли версия и дата вступления определения в силу?

14. Определено ли, пересчитывается ли история при изменении?

15. Проверяется ли соответствие документа реальной реализации?

16. Может ли пользователь увидеть определение из отчёта?

Если на часть вопросов нет ответа, это не повод останавливать весь проект. Но такие пробелы должны оставаться видимыми и не маскироваться статусом утверждённой метрики.

Итог

Словарь метрик стоит создавать раньше первого дашборда, потому что именно в этот момент названия превращаются в договорённости о смысле, времени, границах и ответственности. После реализации менять эти правила сложнее: они уже распределены между запросами, моделями, фильтрами и ожиданиями пользователей.

Рабочий словарь хранит не только формулу. Он связывает метрику с бизнес-вопросом, сущностью, источником, временной логикой, проверками, владельцем, потребителями и версией. Связи между записями позволяют оценивать влияние изменений, а статусы отделяют обсуждаемое определение от разрешённого к использованию.

Начать можно с обычной таблицы. Но структура должна допускать дальнейший переход к metrics as code, каталогу данных и семантическому слою. Тогда словарь перестаёт быть документом, который читают только во время согласования, и становится частью аналитической архитектуры.

Хороший результат здесь не в количестве описанных терминов. Он в том, что пользователь, аналитик и разработчик могут независимо ответить, что измеряет показатель, на каких данных он построен, какая версия действует и что изменится при пересмотре определения.