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

Документация в dbt не отдельный артефакт, а часть кода — и граф зависимостей строится сам.

dbt docs — авто-генерируемый сайт документации, собирающий описания моделей и колонок из YAML и интерактивный граф зависимостей (lineage) из DAG.

Проблема устаревшей документации

Документация в отдельной вики живёт ровно до первого изменения схемы — потом она лжёт. dbt решает это, держа описания рядом с кодом, в тех же YAML-файлах, где тесты. Меняешь модель — правишь описание в том же ревью. А граф зависимостей вообще не пишут руками: dbt строит его из тех же ref().

Описания в YAML

models:
  - name: fct_orders
    description: "Витрина заказов: одна строка на заказ с суммой и статусом."
    columns:
      - name: order_id
        description: "Первичный ключ заказа."
        tests: [unique, not_null]
      - name: amount
        description: "Сумма заказа в рублях, после конвертации из копеек."
      - name: status
        description: "Статус: paid, shipped, delivered, cancelled."

Описания и тесты живут в одном месте — это и контракт модели, и её документация.

Генерация и просмотр сайта

# Собрать документацию (соберёт descriptions + граф)
dbt docs generate

# Поднять локальный сайт документации
dbt docs serve

Откроется веб-страница: список моделей, их колонки, тесты, скомпилированный SQL и — главное — интерактивный граф зависимостей.

Lineage: граф влияния

source.raw.orders --> stg_orders --> int_orders --> fct_orders --> (BI-дашборд)

Клик по узлу fct_orders покажет:
  - что он читает (upstream): int_orders, stg_*
  - кто читает его (downstream): какие витрины/отчёты сломаются при правке

Граф отвечает на самый частый вопрос аналитика: «если я изменю эту модель, что сломается?». downstream-узлы показывают всё, что зависит от вашей правки.

Как работает под капотом

dbt docs generate собирает два артефакта: manifest.json (полная карта проекта: модели, тесты, описания, зависимости из ref()/source()) и catalog.json (информация о колонках и типах из хранилища). dbt docs serve поднимает статический сайт, который рендерит эти JSON в навигацию и граф. Поскольку lineage строится из реального DAG, он всегда соответствует коду — устареть не может.

Частые ошибки

Вести документацию отдельно от кода. Она устареет; держите descriptions в YAML рядом с моделью.
Описывать только модель, но не колонки. Пользователю важнее всего смысл конкретных полей.
Забывать dbt docs generate в CI/деплое. Тогда опубликованная документация отстаёт от прода.

Итоги

Описания моделей и колонок живут в YAML рядом с тестами — документация как код.
dbt docs generate + serve дают сайт с описаниями и интерактивным графом lineage.
Граф строится из ref()/source() и отвечает «что сломается, если я это изменю».