Просмотр документации
dbt предоставляет интуитивно понятные и масштабируемые инструменты для просмотра документации dbt. Подробная документация крайне важна для разработчиков и других заинтересованных сторон, чтобы сформировать общее понимание контекста вашего dbt‑проекта.
Вы можете просматривать документацию тремя взаимодополняющими способами в зависимости от ваших потребностей:
| Опция | Описание | Доступность |
|---|---|---|
| dbt Docs (устаревшая версия) | Создаёт статический сайт с графом зависимостей моделей, метаданными и документацией, который можно разместить на вашем веб-сервере (например, в S3 или Netlify). | dbt v1 или тариф Developer в dbt |
| dbt Docs v2 | Современный высокопроизводительный каталог с открытым исходным кодом, созданный для потребителей данных. Включает обновлённый интерфейс, высокую производительность для крупных проектов, метаданные Semantic Layer и граф зависимостей на уровне столбцов (dbt v2). Предоставляется в виде статического сайта, который можно разместить где угодно. | dbt v2 (только локально) |
| Catalog | Наиболее развитое решение для работы с документацией в dbt. Расширяет возможности dbt Docs, предоставляя динамический интерфейс, работающий в реальном времени, с подробными метаданными, настраиваемыми представлениями, глубоким анализом вашего проекта и ресурсов, а также инструментами для совместной работы. | Тарифы Starter, Enterprise или Enterprise+ в dbt |
Навигация по документации
В следующих разделах описано, как ориентироваться в документации в Catalog и dbt Docs.
Каталог StarterEnterpriseEnterprise +
Catalog предлагает динамичный интерактивный способ изучения ваших моделей, источников и происхождения данных. Чтобы открыть Catalog, выберите пункт Catalog в меню навигации dbt.
Пример страницы с деталями ресурса в Catalog и его lineage.
Откройте Catalog на вкладке lineage задания, дважды щёлкнув узел графа происхождения данных.Catalog предлагает пользователям широкий набор возможностей, которые упрощают навигацию по проектам данных и помогают лучше в них разобраться:
- Интерактивная визуализация происхождения данных в DAG вашего проекта, позволяющая понять связи между ресурсами.
- Строка поиска ресурсов с широким набором фильтров для быстрого и эффективного поиска ресурсов проекта.
- Сведения о производительности моделей: доступ к метаданным запусков dbt для углублённого анализа производительности и качества моделей.
- Рекомендации по проекту с предложениями по улучшению покрытия тестами и документации во всей вашей среде данных.
- Индикаторы состояния данных для мониторинга состояния и производительности каждого ресурса.
- История запросов к моделям для отслеживания запросов потребителей к вашим моделям и более глубокого понимания использования данных.
- Зависимые exposures для автоматического представления соответствующих моделей данных из таких инструментов, как Tableau, и повышения их видимости.
Любой пользователь с лицензией разработчика или лицензией только для чтения может исследовать ваши проекты в Catalog. Добавьте столько лицензий только для чтения, сколько нужно, чтобы поделиться документацией с заинтересованными сторонами — отдельный сайт документации не потребуется.
Дополнительные сведения и инструкции по исследованию происхождения данных, навигации по ресурсам, просмотру истории запросов к моделям и индикаторов состояния данных, доступности функций и другим вопросам см. в разделе Исследование данных с помощью Catalog.
dbt Docs v2
dbt Docs v2 — это каталог нового поколения с открытым исходным кодом, доступный при использовании dbt v2. Он предназначен для потребителей данных (аналитиков, пользователей BI, специалистов по данным и заинтересованных сторон), которым нужно понимать, какие данные существуют, как они были созданы и можно ли им доверять.
dbt Docs v2 доступен только в самостоятельно размещённых установках dbt v2. В dbt platform задания на dbt v2 автоматически обновляют метаданные Catalog, поэтому используйте Catalog для исследования проекта и предоставляйте всем пользователям, которым это необходимо, доступ только для чтения без ограничений. Подробнее см. в разделе Поведение на платформе.
Основные улучшения по сравнению с dbt Docs:
- Производительность: Улучшенная работа с крупными проектами dbt. Браузер запрашивает компактные, предварительно сформированные индексные файлы с помощью DuckDB-WASM (WebAssembly), а не загружает весь
manifest.json. - Обновлённый интерфейс: Визуально согласован с платформой dbt; улучшены навигация и поиск ресурсов.
- Метаданные Semantic Layer: Отображает скомпилированную SQL-логику, доступные для запросов измерения и определения метрик из вашего dbt Semantic Layer.
- Происхождение данных на уровне столбцов: Доступно при использовании dbt v2.
- Статическое размещение: Команда
dbt docs generateсоздаёт автономный статический сайт — без сервера и активного подключения к хранилищу данных, — который можно разместить на любом файловом хостинге, например S3, GitHub Pages или Netlify.
Чтобы сгенерировать и запустить dbt Docs v2 с помощью dbt v2, выполните dbt docs generate для сборки сайта, а затем dbt docs serve для его локального просмотра. Команда dbt docs generate компилирует проект и записывает индекс за один запуск.
Чтобы включить типы столбцов моделей, выведенные из вашего 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, а подробное описание флагов и создаваемых ими метаданных — в разделе Команды для генерации метаданных.
Самостоятельное размещение dbt Docs v2
Поскольку dbt docs generate создаёт автономный статический сайт — одностраничное приложение и индексные файлы Parquet без серверного движка запросов, — вы можете разместить его на любом хостинге статических файлов вместо локального запуска dbt docs serve. Во время работы браузер загружает DuckDB-WASM из сети доставки контента (CDN) и напрямую запрашивает данные из Parquet, поэтому для просмотра достаточно сервера статических файлов и исходящего доступа в интернет для подключения к CDN.
Сгенерируйте автономный каталог и опубликуйте его на выбранном хостинге:
dbt docs generate --output-dir site
Эта команда создаёт каталог site/ (приложение, ресурсы с хешами в именах файлов и копию индекса), который можно разместить на S3, GitHub Pages, Netlify, GitLab Pages или любом аналогичном хостинге статических файлов. Чтобы обновить документацию, повторно сгенерируйте сайт и опубликуйте его заново.
dbt Docs (устаревшая версия)
dbt Docs предоставляет полезные сведения о ваших проектах dbt v1 или проектах dbt на тарифном плане Developer. Интерфейс позволяет переходить к документации конкретных моделей. Это может выглядеть примерно так:
Автоматически сгенерированная документация для модели dbtЗдесь вы видите представление структуры проекта, markdown‑описание модели и список всех колонок модели с документацией.
На странице dbt Docs нажмите зелёную кнопку в правом нижнем углу страницы, чтобы развернуть «мини‑карту» вашего DAG. В этой панели отображаются непосредственные родители и потомки модели, которую вы изучаете.
Открытие мини‑карты DAGВ этом примере модель fct_subscription_transactions имеет только одного прямого родителя. Нажав кнопку Expand в правом верхнем углу окна, можно развернуть граф по горизонтали и увидеть полный lineage модели. Этот lineage можно фильтровать с помощью флагов --select и --exclude, которые соответствуют семантике model selection syntax. Кроме того, вы можете щёлкнуть правой кнопкой мыши для взаимодействия с DAG, перехода к документации или обмена ссылками на визуализацию графа с коллегами.
Полный lineage для модели dbtРазвёртывание сайта документации
Без труда публикуйте документацию в Catalog или dbt Docs, чтобы сделать её доступной вашим командам.
Команда dbt docs serve предназначена только для локального или dev‑хостинга сайта документации. Пожалуйста, используйте один из методов, перечисленных в следующем разделе (или аналогичный), чтобы обеспечить безопасный хостинг документации.
Каталог StarterEnterpriseEnterprise +
Catalog автоматически обновляет документацию после каждого запуска задания в среде production или staging, используя сгенерированные метаданные. Это означает, что в нём всегда доступны актуальные результаты для вашего проекта без необходимости ручного развёртывания. Подробнее о том, как Catalog использует метаданные для автоматического обновления документации, см. в разделе Генерация метаданных.
Чтобы узнать, как развернуть сайт документации, см. раздел Создание и просмотр документации с помощью dbt.
dbt Docs (устаревший инструмент)
dbt Docs был разработан так, чтобы его было легко разместить в интернете. Сайт является «статическим», то есть для предоставления доступа к документации не нужны «динамические» серверы. Разместить документацию можно несколькими способами:
- Разместить на Amazon S3 (при необходимости — с ограничениями доступа по IP-адресам)
- Опубликовать с помощью Netlify
- Использовать собственный веб-сервер, например Apache/Nginx
- Если вы используете тарифный план dbt Developer, см. раздел Создание и просмотр документации с помощью dbt, чтобы узнать, как развернуть сайт документации.
Если вы хотите использовать Catalog, чтобы воспользоваться всеми возможностями документации dbt, зарегистрируйтесь для бесплатного пробного использования dbt или свяжитесь с нами.
