Создание и просмотр документации с dbt Cloud
dbt Cloud позволяет генерировать документацию для вашего проекта и платформы данных. Документация автоматически обновляется с новой информацией после успешного выполнения задания, обеспечивая точность и актуальность.
По умолчанию в dbt Cloud используется dbt Explorer, доступный на планах Team или Enterprise. Используйте dbt Explorer для просмотра ресурсов вашего проекта (таких как модели, тесты и метрики) и их родословной, чтобы лучше понять его текущее состояние в производстве.
Обратитесь к документации для получения более подробной информации о конфигурации.
Этот переход делает dbt Docs устаревшей функцией документации в dbt Cloud. dbt Docs по-прежнему доступен и предлагает базовую документацию, но не предоставляет такую же скорость, метаданные или видимость, как dbt Explorer. dbt Docs доступен для планов разработчиков dbt Cloud или пользователей dbt Core.
Настройка задания для документации
dbt Explorer использует метаданные, сгенерированные после каждого выполнения задания в производственной или промежуточной среде, обеспечивая всегда актуальные результаты проекта. Чтобы просмотреть более богатые метаданные, вы можете настроить документацию для задания в dbt Cloud, когда редактируете настройки задания или создаете новое задание.
Настройте задание на генерацию метаданных при его выпол нении. Если вы хотите просматривать столбцы и статистику для моделей, источников и снимков в dbt Explorer, этот шаг необходим.
Чтобы настроить задание на генерацию документации:
- В левом верхнем углу нажмите Deploy и выберите Jobs.
- Создайте новое задание или выберите существующее и нажмите Settings.
- В разделе Execution Settings выберите Generate docs on run и нажмите Save.
Настройка задания для генерации документации
Примечание: для пользователей dbt Docs необходимо настроить задание на генерацию документации при его выполнении, а затем вручную связать это задание с вашим проектом. Перейдите к настройке документации проекта, чтобы ваш проект генериро вал документацию при выполнении этого задания.
Вы также можете добавить команду dbt docs generate в список команд в шагах выполнения задания. Однако вы можете ожидать разные результаты при добавлении команды в шаги выполнения по сравнению с настройкой задания, выбрав флажок Generate docs on run.
Рассмотрите следующие варианты и результаты:
| Варианты | Результаты |
|---|---|
| Выбор флажка | Выберите флажок Generate docs on run, чтобы автоматически генерировать обновленную документацию проекта каждый раз при выполнении вашего задания. Если этот конкретный шаг в вашем задании не удастся, задание все равно может быть успешным, если все последующие шаги будут успешными. |
| Добавить как шаг выполнения | Добавьте dbt docs generate в список команд в шагах выполнения задания в любом порядке, который вы предпочитаете. Если этот конкретный шаг в вашем задании не удастся, задание не удастся, и все последующие шаги будут пропущены. |
Чтобы создать и запланировать задания только для документации в конце ваших производственных заданий, добавьте команду dbt compile в раздел Commands.
dbt Docs
dbt Docs, доступный на планах разработчиков или для пользователей dbt Core, генерирует веб-сайт из вашего проекта dbt с помощью команды dbt docs generate. Он предоставляет центральное место для просмотра ресурсов вашего проекта, таких как модели, тесты и родословная — и помогает понять данные в вашем хранилище.
Настройка документации проекта
Вы настраиваете документацию проекта для генерации документации, когда выполняется задание, которое вы настроили в предыдущем разделе. В настройках проекта укажите задание, которое генерирует артефакты документации для этого проекта. После настройки этого параметра последующие выполнения задания автоматически будут включать шаг для генерации документации.
- В dbt Cloud нажмите на имя вашей учетной записи в левом боковом меню и выберите Account settings.
- Перейдите в Projects и выберите проект, которому нужна документация.
- Нажмите Edit.
- В разделе Artifacts выберите задание, которое должно генерировать документацию при выполнении, и нажмите Save.
Настройка документации проекта
Для более богатого и интерактивного опыта попробуйте dbt Explorer, доступный на планах Team или Enterprise. Он включает в себя слои карты вашего DAG, поиск по ключевым словам, взаимодействие с IDE, производительность моделей, рекомендации по проекту и многое другое.
Генерация документации
Чтобы сгенерировать документацию в dbt Cloud IDE, выполните команду dbt docs generate в Command Bar в dbt Cloud IDE. Эта команда сгенерирует документацию для вашего проекта dbt, как он существует в разработке в вашей сессии IDE.
После выполнения dbt docs generate в dbt Cloud IDE нажмите на значок над деревом файлов, чтобы увидеть последнюю версию вашей документации, отображенную в новом окне браузера.
Просмотр документации
После того как вы настроите задание на генерацию документации для вашего проекта, вы можете нажать Explore в навигации, а затем нажать на dbt Docs. Должна открыться документация вашего проекта. Эта ссылка всегда поможет вам найти самую последнюю версию документации вашего проекта в dbt Cloud.
Эти сгенерированные документы всегда показывают последний полностью успешный запуск, что означает, что если у вас есть какие-либо неудачные задачи, включая тесты, то вы не увидите изменений в документации от этого запуска. Если вы не видите полностью успешного запуска, то вы не увидите никаких изменений в документации.
dbt Cloud IDE позволяет просматривать документацию для вашего проекта dbt, пока ваш код все еще находится в разработке. С помощью этого рабочего процесса вы можете проверять и подтверждать, как будет выглядеть сгенерированная документация вашего проекта, прежде чем ваши изменения будут выпущены в производство.