Словарь данных арбитражной команды: поля, владельцы и проверки

Редакция mevrica

Аналитика5 мин чтения

Обновлено 2 августа 2026 г.

Словарь данных арбитражной команды — это договор о смысле полей между рекламным кабинетом, трекером, landing, партнёрской программой и финансовым отчётом. Без него одинаковое слово conversion означает клик по кнопке, регистрацию, pending или approved в зависимости от автора dashboard. Технически корректный SQL тогда даёт управленчески неверный ответ.

Критерий готовности

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

Начните не с колонок, а с grain

Grain описывает одну строку: событие, клик, текущий статус конверсии, версия статуса, дневной срез кампании или финансовое движение. Если grain не указан, сумму легко посчитать дважды после join. Например, одна конверсия с тремя версиями статуса не равна трём конверсиям.

Минимальная карточка поля

Примеры показывают форму, а не готовую спецификацию production. Реальные названия источников, владельцы и допуски берутся из инфраструктуры команды.

Машинное имя и подпись — разные вещи

field_name остаётся стабильным для кода. Человеческая подпись может быть русской и меняться ради понятности. Нельзя использовать label «Доход» без уточнения: начисленный, approved, payable или settled; gross, net или доля партнёра; валюта события или отчёта.

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

• clicked_at — момент клика у согласованного источника
• occurred_at — бизнес-время целевого события
• received_at — получение системой
• decided_at — решение по статусу
• settled_at — фактическое денежное движение

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

NULL — не ноль и не пустая строка

Для каждого nullable-поля задайте смысл отсутствия. NULL payout может означать «ставка неприменима», «решение не созрело» или «данные потеряны» — это разные состояния. Если различие важно, создайте status/reason field вместо перегрузки одного NULL.

Enum требует жизненного цикла

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

CREATE TABLE status_dictionary (
  status_code text NOT NULL,
  dictionary_version text NOT NULL,
  definition text NOT NULL,
  valid_from timestamptz NOT NULL,
  valid_to timestamptz,
  replacement_code text,
  owner_role text NOT NULL,
  PRIMARY KEY (status_code, dictionary_version)
);

Schema проверяет форму, словарь — смысл

JSON Schema может закрепить required properties, типы и допустимые значения. Но проверка типа integer не доказывает, что amount_minor относится к нужной валюте или статусу. Поэтому техническая схема ссылается на словарь и его definition_version.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["event_id", "event_type", "occurred_at", "schema_version"],
  "properties": {
    "event_id": {"type": "string", "minLength": 1},
    "event_type": {"enum": ["registration", "qualified_action", "status_change"]},
    "occurred_at": {"type": "string", "format": "date-time"},
    "schema_version": {"type": "integer", "minimum": 1}
  },
  "additionalProperties": false
}

Список event_type иллюстративный. Реальный enum обязан совпадать с видимым бизнес-процессом и не использовать gambling-термины там, где продукт или условия определяют события иначе.

Владение на двух уровнях

Business owner утверждает определение и допустимое решение. Technical owner отвечает за получение, хранение и SLA. Data steward следит за документацией и совместимостью. Роль фиксируется, а не привязывается навечно к имени сотрудника.

Изменение определения

1. Создать proposal с причиной и затронутыми потребителями.
2. Сравнить старую и новую семантику.
3. Определить backward compatibility.
4. Добавить новую версию схемы и словаря.
5. Проверить producer и consumer на fixtures.
6. Запустить dual-read или canary при необходимости.
7. Обновить dashboard и обучение.
8. Закрыть старую версию только после миграции.

Автоматические проверки

SELECT
  count(*) FILTER (WHERE event_id IS NULL OR event_id='') AS missing_id,
  count(*) - count(DISTINCT event_id) AS duplicate_id,
  count(*) FILTER (WHERE occurred_at > received_at + interval '10 minutes') AS future_event,
  count(*) FILTER (WHERE currency IS NOT NULL AND amount_minor IS NULL) AS currency_without_amount,
  count(*) FILTER (WHERE schema_version NOT IN (:supported_versions)) AS unsupported_schema
FROM raw_events
WHERE received_at >= :check_start AND received_at < :check_end;

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

Как внедрять без большого проекта

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

Не копируйте описание из интерфейса платформы без версии

Внешние определения и наборы полей меняются. Сохраняйте URL первичной документации, дату проверки и собственное правило преобразования в аналитический слой.

Источники и границы применимости

JSON Schema: пошаговое создание схемы · OpenTelemetry: registry semantic conventions

Вывод

Data dictionary превращает набор колонок в договор о данных. Grain защищает от двойного счёта, временная семантика — от неверных когорт, versioning — от тихой смены смысла, а владельцы и проверки делают определения исполнимыми. Начинайте с полей, влияющих на деньги, и связывайте документацию с реальными контрактами и тестами.