О командах dbt docs
С dbt v2 используйте dbt Docs v2, чтобы создать и просмотреть документацию проекта локально. Команда dbt docs generate собирает сайт, а dbt docs serve запускает предпросмотр.
Чтобы создать только метаданные каталога (catalog.json), используйте флаг --write-catalog.
dbt Docs v2 предназначен для локального запуска и размещения в собственной инфраструктуре. В dbt platform используйте Catalog: это облачное представление документации, которое задания обновляют автоматически. Подробнее см. Поведение на платформе.
dbt Docs v2
Сайт dbt Docs v2 собирается локально или в вашем пайплайне, например в GitHub Actions, и размещается в вашей инфраструктуре. На dbt platform вместо него используется Catalog. Подробнее см. Поведение на платформе.
При компиляции или сборке проекта v2 создаёт артефакты Parquet вместо статического manifest.json, который загружался в браузер. Команда dbt docs generate экспортирует сайт как набор статических файлов: одностраничное приложение и эти артефакты. Их можно разместить на любом файловом хостинге. Браузер читает Parquet напрямую через DuckDB-WASM (WebAssembly), поэтому отдельный сервер с состоянием не нужен и просмотр остаётся быстрым даже для крупных проектов.
Сборка сайта
Команда dbt docs generate компилирует проект, записывает индекс и экспортирует сайт документации:
dbt docs generate
По умолчанию dbt записывает сайт в target/: target/index.html, target/assets/ и индекс в target/index/. Структура совпадает с dbt v1. Файл index.html можно отдавать из target/ так же, как в v1, поэтому пайплайн с командой dbt docs generate && mv target public продолжит работать.
Чтобы записать автономную копию сайта в другой каталог, используйте --output-dir:
dbt docs generate --output-dir site
Будет создан каталог site/ с приложением, ресурсами с хешами в именах и копией индекса. Его можно разместить в S3, GitHub Pages, Netlify, GitLab Pages или на аналогичном хостинге статических файлов.
Чтобы пропустить компиляцию и экспортировать существующий индекс, используйте --no-compile. Если индекса нет, команда завершится ошибкой:
dbt docs generate --no-compile
Зависимости столбцов и дополнительные метаданные
Чтобы добавить типы столбцов, выведенные из SQL моделей, и зависимости на уровне столбцов, запустите dbt build, dbt run или dbt compile с флагами --generate-info-schema и --static-analysis strict, затем экспортируйте сайт:
dbt build --generate-info-schema --static-analysis strict
dbt docs generate --no-compile
Флаг --no-compile пропускает этап компиляции в dbt docs generate и экспортирует существующий индекс.
Если при сборке сайта сведения о зависимостях столбцов не были добавлены, dbt Docs v2 скрывает соответствующие функции.
Локальный запуск dbt Docs v2
Чтобы просмотреть сайт локально, выполните:
dbt docs serve
Команда dbt docs serve открывает документацию на вашем компьютере. На dbt platform для просмотра проекта используйте Catalog. Подробнее см. Поведение на платформе.
Команда dbt docs serve собирает сайт, если его ещё нет или он старше индекса, а затем отдаёт статические файлы. По умолчанию сервер запускается на порту 8580, и сайт открывается в браузере. Порт можно изменить флагом --port:
dbt docs serve --port 8081
Флаг --target-path позволяет изменить каталог, из которого dbt читает артефакты:
dbt docs serve --target-path ~/Developer/internal-analytics/target
Сайт состоит из статических файлов, поэтому вместо локального сервера можно разместить его в объектном хранилище или на хостинге статических сайтов.
Страница обзора проекта
Как и в dbt Docs v1, начальная страница dbt Docs v2 использует блок документации __overview__. dbt ищет блоки {% docs %} в каталогах docs-paths, поэтому файл models/overview.md находится по умолчанию. Файл docs/overview.md будет найден, только если в проекте задано docs-paths: ["docs"]. Если блок обзора не задан, dbt использует стандартную страницу.
Флаг --write-catalog
Флаг --write-catalog создаёт артефакт catalog.json с метаданными таблиц и представлений, созданных моделями проекта. Флаг только собирает метаданные. Чтобы собрать сайт документации, используйте dbt Docs v2.
При локальном запуске dbt добавляйте этот флаг явно. Он поддерживается следующими командами:
dbt builddbt rundbt parsedbt compile
Пример:
dbt build --write-catalog
Задания dbt v2 на dbt platform автоматически обновляют метаданные Catalog при каждом запуске, поэтому флаг --write-catalog в них не нужен. Подробнее см. Поведение на платформе dbt.
Локальный запуск
При локальном запуске dbt v2 добавьте флаг --write-catalog, чтобы сгенерировать метаданные каталога:
dbt build --write-catalog
Отличие от docs generate
Обе команды записывают артефакты. Сайт документации, который можно открыть в браузере, создаёт только dbt docs generate.
Флаг --write-catalog | Команда dbt docs generate | |
|---|---|---|
| Что создаёт | catalog.json и артефакты, которые команда создаёт и без флага | index.html, assets/ и файлы индекса |
| Для чего используется | Метаданные для Catalog и API метаданных | Статический сайт, который можно просмотреть через dbt docs serve или разместить на хостинге |
| Где работает | Локально и на dbt platform. В заданиях dbt v2 на платформе команда добавляется автоматически. | Только локально в v2. В заданиях dbt platform вместо неё выполняется dbt compile --write-catalog |
Команды для сбора метаданных
Флаги собирают разные метаданные для разных задач. Выберите подходящую команду из списка. В Справочнике флагов указано, какие данные создаёт каждый флаг и куда он их записывает.
-
Чтобы показать выведенные типы столбцов моделей и зависимости столбцов в dbt Docs v2:
dbt build --generate-info-schema --static-analysis strict
dbt docs generate --no-compile -
Чтобы создать информационную схему dbt с выведенными типами столбцов моделей и зависимостями столбцов:
dbt build --generate-info-schema --static-analysis strict -
Чтобы создать информационную схему dbt с выведенными типами и зависимостями столбцов моделей, типами из хранилища и всеми столбцами источников, используемых выбранными узлами:
dbt build --generate-info-schema --static-analysis strict --write-catalog -
Чтобы создать информационную схему dbt только с типами столбцов из хранилища:
dbt build --generate-info-schema --write-catalog -
Чтобы создать
catalog.jsonс типами столбцов из хранилища:dbt build --write-catalog
Справочник флагов
В таблице указано, какие метаданные создаёт каждый флаг и куда они записываются:
| Флаг | Описание | Куда записываются данные |
|---|---|---|
--generate-info-schema | Создаёт информационную схему dbt. Добавьте --static-analysis strict, чтобы включить выведенные типы и зависимости столбцов моделей. | target/info_schema/v1/ |
--static-analysis strict | Включает выведенные типы и зависимости столбцов при использовании вместе с --generate-info-schema. | Зависит от флага, с которым используется |
--write-catalog | Создаёт catalog.json с типами столбцов из хранилища. Вместе с --generate-info-schema в dbt build или dbt run записывает типы из хранилища и все столбцы источников для выбранных узлов в информационную схему dbt. | target/catalog.json (и target/info_schema/v1/ вместе с --generate-info-schema) |
dbt Docs v2 читает метаданные из информационной схемы dbt. Файл catalog.json — отдельный артефакт для внешних инструментов.
Поведение на платформе dbt
dbt Docs v2 предназначен для локального запуска и размещения в собственной инфраструктуре. На dbt platform используйте Catalog, где доступно актуальное представление проекта:
- Каждый запуск задания v2 в dbt platform автоматически обновляет метаданные Catalog. Отдельный шаг генерации документации не нужен.
- Если добавить в задание шаг
dbt docs generate, dbt автоматически выполнит вместо негоdbt compile --write-catalogи направит вас в Catalog. Задание не создаст статический сайт или файлindex.html. - Чтобы дать коллегам, которые не разрабатывают в dbt, доступ к проекту, добавьте необходимое число мест с правом чтения. Доступ к Catalog включён и для разработчиков, и для пользователей с правом чтения.
