Документация и dbt docs

В «Гонец» пришла Лена, новый аналитик. Первый же вопрос: «late_pct в mart_zone_daily это доля от всех заказов или только от доставленных? И откуда в витрине норматив по зоне?» Ты отвечаешь в чате. Через неделю тот же вопрос задаёт бухгалтерия, ещё через неделю Отто. Ответ лежит у тебя в голове и в истории переписки. Его место рядом с кодом, там, где его найдёт любой.

Подписи в музее

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

Документация в dbt это такие таблички у моделей и колонок. Пишут их в том же YAML, где тесты, и в том же коммите, где появилась модель.

description у модели и колонки

У любой модели, колонки, источника и сида есть свойство description:

# models/marts/_schema.yml
version: 2

models:
  - name: mart_zone_daily
    description: Опоздания по зонам за каждый день. Дашборд Отто.
    columns:
      - name: late_pct
        description: >
          Доля опоздавших среди чистых доставок за день, в процентах.
          Отменённые заказы и сбои часов в знаменатель не входят.
      - name: target_late_pct
        description: Норматив доли опозданий для зоны из сида zone_targets.

> в YAML склеивает несколько строк в одну, чтобы длинное описание не уходило вправо за экран. Описания лежат рядом с тестами той же колонки: открыл файл, и видно и правило, и смысл.

Длинные тексты в блоках docs

Иногда описание длиннее пары строк. Например, определение «чистой доставки» нужно в трёх моделях, и копировать абзац в каждую не хочется. Для этого есть блок docs: именованный текст в Markdown в файле .md рядом с моделями:

<!-- models/marts/_docs.md -->
{% docs clean_delivery %}
Чистая доставка: заказ в статусе `delivered`, у которого время доставки
не раньше времени забора. 24 заказа со сбоем часов приложения курьера
в чистые доставки не входят.
{% enddocs %}

В YAML на блок ссылаются функцией doc:

      - name: deliveries
        description: '{{ doc("clean_delivery") }}'

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

Граф проекта

Документация это не только тексты. Из ref() и source() dbt знает, какая модель из каких собрана. Этот граф называют lineage, происхождением данных. Он отвечает на вопрос Лены «откуда в витрине норматив»: mart_zone_daily берёт его из dim_zones, а та из сида zone_targets. И на обратный вопрос: что сломается на дашборде, если поменять stg_orders.