Сборка и просмотр документации с помощью dbt
dbt позволяет генерировать документацию для вашего проекта и платформы данных. Документация автоматически обновляется новой информацией после полностью успешного запуска job, что обеспечивает её актуальность и точность.
Документация по умолчанию в dbt представлена в Catalog и доступна на тарифных планах Starter, Enterprise или Enterprise+. Используйте Catalog, чтобы просматривать ресурсы вашего проекта (например, модели, тесты и метрики) и их lineage, что помогает лучше понять его текущее production-состояние.
Обратитесь к документации для получения более подробной информации о конфигурации.
Этот сдвиг делает dbt Docs устаревшей функцией документации в dbt. dbt Docs по‑прежнему доступен и предоставляет базовую документацию, однако он не предлагает такую же скорость работы, объем метаданных и уровень видимости, как Catalog. dbt Docs доступен для планов разработчиков dbt или для пользователей dbt Core.
Настройка задания для документации
Catalog использует метаданные, которые генерируются после каждого запуска job в production или staging‑окружении. Это гарантирует, что в нем всегда отображаются самые актуальные результаты проекта. Чтобы просматривать более подробные метаданные, вы можете настроить документацию для job в dbt — при редактировании существующих настроек job или при создании нового job.
Настройте job так, чтобы при его запуске выполнялась генерация метаданных. Если вы хотите просматривать колонки и статистику для моделей, источников и снапшотов в Catalog, этот шаг является обязательным.
Чтобы настроить задание на генерацию документации:
- В левом верхнем углу нажмите Deploy и выберите Jobs.
- Создайте новое задание или выберите существующее и нажмите Settings.
- В разделе Execution Settings выберите Generate docs on run и нажмите Save.
Настройка задания для генерации документации
Примечание: для пользователей dbt Docs необходимо настроить задание на генерацию документации при его выполнении, а затем вручную связать это задание с вашим проектом. Перейдите к настройке документации проекта, чтобы ваш проект генерировал документацию при выполнении этого задания.
Вы также можете добавить команду dbt docs generate в список команд в шагах выполнения задания. Однако вы можете ожидать разные результаты при добавлении команды в шаги выполнения по сравнению с настройкой задания, выбрав флажок Generate docs on run.
Рассмотрите следующие варианты и результаты:
| Loading table... |
Чтобы создать и запланировать задания только для документации в конце ваших производственных заданий, добавьте команду dbt compile в раздел Commands.
dbt Docs
dbt Docs, доступный на планах разработчиков или для пользователей dbt Core, генерирует веб-сайт из вашего проекта dbt с помощью команды dbt docs generate. Он предоставляет центральное место для просмотра ресурсов вашего проекта, таких как модели, тесты и родословная — и помогает понять данные в вашем хранилище.
Настройка документации проекта
Вы настраиваете документацию проекта для генерации документации, когда выполняется задание, которое вы настроили в предыдущем разделе. В настройках проекта укажите задание, которое генерирует артефакты документации для этого проекта. После настройки этого параметра последующие выполнения задания автоматически будут включать шаг для генерации документации.
- В dbt нажмите на имя вашей учетной записи в левом боковом меню и выберите Account settings.
- Перейдите в раздел Projects и выберите проект, для которого требуется документация.
- Нажмите Edit.
- В разделе Artifacts выберите job, который должен генерировать документацию при запуске, и нажмите Save.
Configuring project documentation
Для более богатого и интерактивного опыта попробуйте Catalog, доступный на планах Starter, Enterprise или Enterprise+. Он включает визуализацию DAG в виде слоев карты, поиск по ключевым словам, интеграцию с Studio IDE, показатели производительности моделей, рекомендации по проекту и многое другое.
Генерация документации
Чтобы сгенерировать документацию в Studio IDE, выполните команду dbt docs generate в Command Bar в Studio IDE. Эта команда сгенерирует документацию для вашего dbt‑проекта в том виде, в каком он существует в среде разработки в рамках вашей IDE‑сессии.
После выполнения dbt docs generate в Studio IDE нажмите на иконку над деревом файлов, чтобы открыть последнюю версию вашей документации, отрендеренную в новом окне браузера.
Просмотр документации
После того как вы настроите задание для генерации документации вашего проекта, вы сможете нажать Explore в навигации, а затем выбрать dbt Docs. После этого откроется документация вашего проекта. Эта ссылка всегда будет вести вас к самой актуальной версии документации вашего проекта в dbt.
Эти сгенерированные документы всегда показывают последний полностью успешный запуск, что означает, что если у вас есть какие-либо неудачные задачи, включая тесты, то вы не увидите изменений в документации от этого запуска. Если вы не видите полностью успешного запуска, то вы не увидите никаких изменений в документации.
Studio IDE позволяет просматривать документацию вашего проекта dbt, пока код всё ещё находится в разработке. Такой рабочий процесс даёт возможность заранее изучить и проверить, как будет выглядеть сгенерированная документация проекта, ещё до того, как изменения будут выведены в продакшен.
