dbt docs generate и serve

В предыдущих уроках мы писали description и doc blocks. Теперь — как превратить их в работающий UI, где аналитики ищут модели, читают descriptions, смотрят DAG-граф зависимостей.

dbt не имеет «облачного UI» из коробки — это локальная статическая веб-страница, которую генерирует команда dbt docs generate, а потом раздаёт dbt docs serve (или хостит на любом static-сервере).

В этом уроке — что генерится, что в UI, типичные паттерны деплоя.

Две команды: generate и serve

dbt docs generate    # генерит документацию
dbt docs serve       # запускает локальный веб-сервер для просмотра

Это две независимые операции. generate собирает данные, serve показывает их в браузере.

В CI/CD типично: dbt docs generate -> push артефактов в S3 / GitHub Pages / Netlify. dbt docs serve — для локальной разработки.

Что делает dbt docs generate

Под капотом — три шага:

В итоге в папке target/ появляются файлы:

target/
  manifest.json     ← структура проекта (models, dependencies, descriptions)
  catalog.json      ← actual schemas из warehouse
  run_results.json  ← результаты последнего run/test (если был)
  graph.gpickle     ← Python-pickle графа (для internal dbt операций)
  partial_parse.msgpack  ← cache парсинга
  compiled/         ← скомпилированный SQL каждой модели
  run/              ← SQL запросы, которые выполнялись
  index.html        ← статический UI (это что показывает dbt docs serve)

Размер target/ обычно — десятки МБ для проекта на 100 моделей. Для огромных проектов (1000+ моделей) — может быть 100+ МБ.

Что делает dbt docs serve

После dbt docs generate запускаете:

dbt docs serve
# Serving docs at 0.0.0.0:8080
# Press Ctrl+C to exit.

Открывается локальный HTTP-сервер на порту 8080. Заходите в браузере на http://localhost:8080 — видите UI.

Под капотом — это обычный static file server. Раздаёт файлы из target/. Никакой динамики, никаких запросов в warehouse — всё уже в manifest.json и catalog.json.

Поэтому dbt docs serve можно заменить на любой static-сервер:

cd target && python -m http.server 8080
# или
cd target && npx serve

Это значит — легко хостится на GitHub Pages / Netlify / S3 + CloudFront / любом nginx.

Структура UI

При открытии UI:

Что на странице модели

Открыв fct_orders в UI, видим:

1. Header: имя модели, тип (model / seed / snapshot / source), путь к файлу.
2. Description: rendered markdown из YAML / doc block.
3. Columns: таблица с колонками — name, type, description, tests.
4. Details (collapsible): config (materialized, schema), tags, meta.
5. Code: исходный SQL (raw) + compiled SQL.
6. Tests: список тестов на этой модели.
7. Lineage graph: визуализация DAG — кто upstream, кто downstream.

Это must-have для аналитика: открыл модель -> за 30 секунд понял что это, какие колонки, откуда приходит, кто использует.

Lineage graph — самая ценная часть

Граф зависимостей — главная фича dbt docs. Кнопка справа внизу View Lineage Graph.

В графе:

• Зелёные узлы — sources.
• Синие узлы — models.
• Жёлтые узлы — seeds.
• Фиолетовые узлы — snapshots.
• Розовые узлы — exposures.

Линии — ref() / source() зависимости. Стрелка от A к B = “A -> B” = “B зависит от A”.

Селекторы графа:

• +model — модель и все upstream.
• model+ — модель и все downstream.
• +model+ — модель + upstream + downstream (full lineage).
• Несколько селекторов — пересечение / объединение.

Это критический инструмент:

• Хотите понять «откуда приходит fct_orders» -> +fct_orders -> видите 5 staging-моделей и source.
• Хотите понять «что сломается, если изменю stg_jaffle__customers» -> stg_jaffle__customers+ -> видите 10 downstream-моделей и 2 exposure’а.
• Onboarding нового member’а: показываете +main_dashboard_mart+ — он за минуту видит весь поток.

Откуда берётся каждая часть UI

Поэтому: если column не имеет description в YAML — UI покажет колонку без описания (имя, тип из catalog, но пусто справа). Если column есть в YAML, но нет в warehouse (модель ещё не была material-ed) — UI покажет description, но не покажет тип.

Для полного UI нужны и dbt run (чтобы материализовать) + dbt docs generate (чтобы сгенерить catalog).

Типичный workflow

В реальной разработке:

# 1. Изменили модель + добавили описание в YAML
vim models/marts/fct_orders.sql
vim models/marts/_marts__models.yml

# 2. Материализовали модель
dbt run --select fct_orders

# 3. Сгенерили документацию (читает обновлённый manifest + catalog)
dbt docs generate

# 4. Открыли UI и проверили
dbt docs serve
# -> http://localhost:8080 -> найти fct_orders -> проверить description, lineage

В CI:

# В pipeline:
dbt deps                     # пакеты
dbt build                    # все модели + тесты
dbt docs generate            # документация
# -> push target/ в S3 / GitHub Pages

Документация деплоится автоматически после каждого merge в main. Аналитики всегда видят актуальную версию.

catalog.json — что внутри

catalog.json — это state warehouse. Для каждой модели:

{
  "nodes": {
    "model.jaffle_shop.fct_orders": {
      "metadata": {
        "type": "BASE TABLE",
        "schema": "marts",
        "name": "fct_orders",
        "database": "jaffle_shop_db"
      },
      "columns": {
        "order_id": {
          "type": "INTEGER",
          "index": 1,
          "name": "order_id",
          "comment": null
        },
        "amount_usd": {
          "type": "DECIMAL(10,2)",
          "index": 2,
          "name": "amount_usd"
        }
      },
      "stats": {
        "row_count": { "value": 50432 },
        "bytes": { "value": 1572864 }
      }
    }
  }
}

Откуда:

• metadata — из INFORMATION_SCHEMA warehouse.
• columns — из SELECT * LIMIT 0 или INFORMATION_SCHEMA.
• stats — warehouse-specific (DuckDB / Postgres имеют свои источники).

Если запустить dbt docs generate без dbt run — модели нет в warehouse, catalog будет пустой для этих моделей. UI покажет descriptions из manifest, но без типов колонок.

manifest.json — структура проекта

manifest.json — это structure dbt-проекта. Содержит все nodes:

{
  "nodes": {
    "model.jaffle_shop.fct_orders": {
      "name": "fct_orders",
      "resource_type": "model",
      "package_name": "jaffle_shop",
      "path": "marts/core/fct_orders.sql",
      "description": "**Grain**: один заказ ...",
      "depends_on": {
        "nodes": [
          "model.jaffle_shop.stg_jaffle__orders",
          "model.jaffle_shop.dim_customers"
        ]
      },
      "columns": {
        "order_id": {
          "name": "order_id",
          "description": "Primary key",
          "data_tests": ["not_null", "unique"]
        }
      },
      "config": {
        "materialized": "table",
        "schema": "marts",
        "tags": ["finance"]
      }
    }
  },
  "sources": { ... },
  "macros": { ... },
  "docs": { ... },
  "exposures": { ... },
  "metadata": {
    "dbt_version": "1.10.2",
    "generated_at": "2026-05-19T10:23:45Z",
    "project_name": "jaffle_shop"
  }
}

Это источник правды для UI. Все descriptions, dependencies, configs, tests — отсюда.

manifest.json также используется для state comparison в CLI (dbt run --state ./prod-manifest --select state:modified).

Хостинг документации

Production-проекты обычно деплоят docs на shared URL:

GitHub Pages — самый простой старт для junior проекта.

Что часто ломается

Попробуй сам

В вашем dbt-проекте:

dbt run            # материализовать все модели
dbt docs generate  # сгенерить документацию
dbt docs serve     # запустить локальный сервер

Откройте http://localhost:8080. Поэкспериментируйте:

1. Поиск: найдите модель по части имени.
2. Открыть модель: посмотрите description, columns, code (raw vs compiled).
3. Lineage graph: нажмите кнопку Lineage. Выделите модель в центре. Видите upstream / downstream.
4. Селекторы графа: введите +fct_orders (для примера) — увидите всех предков.
5. Найти source: откройте source jaffle. Посмотрите freshness section (если настроили loaded_at_field).

Бонус: запустите dbt run без какой-то модели (dbt run --exclude fct_orders). Запустите dbt docs generate. В UI откройте fct_orders — что показывается? Description есть, но columns без types — потому что таблицы в warehouse нет.

Ключевые выводы

1. dbt docs generate собирает manifest.json (структура) и catalog.json (state warehouse).
2. dbt docs serve — простой static HTTP-сервер для target/index.html.
3. UI состоит из: sidebar (project hierarchy), main area (model details: description, columns, code, tests), lineage graph.
4. Lineage graph — самая ценная часть. Селекторы +model, model+, +model+ для навигации.
5. Descriptions в UI отрисовываются как rendered markdown (из YAML + doc blocks).
6. catalog.json пустой для моделей, которые не были dbt run. UI покажет description, но без типов колонок.
7. Хостинг production: GitHub Pages / Netlify / S3 + CloudFront / nginx. Документация — статический сайт.
8. CI pipeline: после dbt build запускайте dbt docs generate и пушите target/ на хостинг.