# Просмотр документации dbt предоставляет интуитивно понятные и масштабируемые инструменты для просмотра документации dbt. Подробная документация крайне важна для разработчиков и других заинтересованных сторон, чтобы сформировать общее понимание контекста вашего dbt‑проекта. Вы можете просматривать документацию тремя взаимодополняющими способами в зависимости от ваших потребностей: | Опция | Описание | Доступность | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**dbt Docs (устаревшая версия)**](#dbt-docs-%D1%83%D1%81%D1%82%D0%B0%D1%80%D0%B5%D0%B2%D1%88%D0%B8%D0%B9-%D0%B8%D0%BD%D1%81%D1%82%D1%80%D1%83%D0%BC%D0%B5%D0%BD%D1%82) | Создаёт статический сайт с графом зависимостей моделей, метаданными и документацией, который можно разместить на вашем веб-сервере (например, в S3 или Netlify). | dbt v1 или тариф Developer в dbt | | [**dbt Docs v2**](#dbt-docs-v2) | Современный высокопроизводительный каталог с открытым исходным кодом, созданный для потребителей данных. Включает обновлённый интерфейс, высокую производительность для крупных проектов, метаданные Semantic Layer и граф зависимостей на уровне столбцов (dbt v2). Предоставляется в виде статического сайта, который можно разместить где угодно. | dbt v2 (только локально) | | [**Catalog**](https://docs.getdbt.tech/docs/explore/explore-projects.md) | Наиболее развитое решение для работы с документацией в dbt. Расширяет возможности dbt Docs, предоставляя динамический интерфейс, работающий в реальном времени, с подробными [метаданными](https://docs.getdbt.tech/docs/explore/explore-projects.md#generate-metadata), настраиваемыми представлениями, глубоким анализом вашего проекта и ресурсов, а также инструментами для совместной работы. | Тарифы Starter, Enterprise или Enterprise+ в dbt | ## Навигация по документации В следующих разделах описано, как ориентироваться в документации в Catalog и dbt Docs. ### Каталог [Starter](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise +](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе") [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md) предлагает динамичный интерактивный способ изучения ваших моделей, источников и происхождения данных. Чтобы открыть Catalog, выберите пункт **Catalog** в меню навигации dbt. [![Пример страницы с деталями ресурса в Catalog и его lineage.](/img/docs/collaborate/dbt-explorer/example-model-details.png?v=2 "Пример страницы с деталями ресурса в Catalog и его lineage.")](#)Пример страницы с деталями ресурса в Catalog и его lineage. [![Откройте Catalog на вкладке lineage задания, дважды щёлкнув узел графа происхождения данных.](/img/docs/collaborate/dbt-explorer/explorer-main-page.gif?v=2 "Откройте Catalog на вкладке lineage задания, дважды щёлкнув узел графа происхождения данных.")](#)Откройте Catalog на вкладке lineage задания, дважды щёлкнув узел графа происхождения данных. Catalog предлагает пользователям широкий набор возможностей, которые упрощают навигацию по проектам данных и помогают лучше в них разобраться: * Интерактивная визуализация происхождения данных в DAG вашего проекта, позволяющая понять связи между ресурсами. * Строка поиска ресурсов с широким набором фильтров для быстрого и эффективного поиска ресурсов проекта. * Сведения о производительности моделей: доступ к метаданным запусков dbt для углублённого анализа производительности и качества моделей. * Рекомендации по проекту с предложениями по улучшению покрытия тестами и документации во всей вашей среде данных. * Индикаторы состояния данных для мониторинга состояния и производительности каждого ресурса. * История запросов к моделям для отслеживания запросов потребителей к вашим моделям и более глубокого понимания использования данных. * Зависимые exposures для автоматического представления соответствующих моделей данных из таких инструментов, как Tableau, и повышения их видимости. Хотите поделиться документацией с заинтересованными сторонами? Любой пользователь с лицензией разработчика или лицензией только для чтения может исследовать ваши проекты в Catalog. Добавьте столько лицензий только для чтения, сколько нужно, чтобы поделиться документацией с заинтересованными сторонами — отдельный сайт документации не потребуется. Дополнительные сведения и инструкции по исследованию происхождения данных, навигации по ресурсам, просмотру истории запросов к моделям и индикаторов состояния данных, доступности функций и другим вопросам см. в разделе [Исследование данных с помощью Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md). ### dbt Docs v2 dbt Docs v2 — это каталог нового поколения с открытым исходным кодом, доступный при использовании dbt v2. Он предназначен для потребителей данных (аналитиков, пользователей BI, специалистов по данным и заинтересованных сторон), которым нужно понимать, какие данные существуют, как они были созданы и можно ли им доверять. Доступность dbt Docs v2 dbt Docs v2 доступен только в [самостоятельно размещённых установках dbt v2](https://docs.getdbt.tech/docs/local/install-dbt.md?version=2). В dbt platform задания на dbt v2 автоматически обновляют метаданные Catalog, поэтому используйте [Catalog](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md) для исследования проекта и предоставляйте всем пользователям, которым это необходимо, доступ только для чтения без ограничений. Подробнее см. в разделе [Поведение на платформе](https://docs.getdbt.tech/reference/commands/cmd-docs.md?version=2#dbt-platform-behavior). Основные улучшения по сравнению с 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`](https://docs.getdbt.tech/docs/build/dbt-information-schema.md) и [`--static-analysis strict`](https://docs.getdbt.tech/docs/build/about-static-analysis.md), а затем экспортируйте сайт: ```shell dbt build --generate-info-schema --static-analysis strict dbt docs generate --no-compile ``` Флаг `--no-compile` пропускает выполняемый по умолчанию этап компиляции в `dbt docs generate` и экспортирует существующий индекс. Полные сведения об использовании см. в разделе [Команды dbt docs](https://docs.getdbt.tech/reference/commands/cmd-docs.md), а подробное описание флагов и создаваемых ими метаданных — в разделе [Команды для генерации метаданных](https://docs.getdbt.tech/reference/commands/cmd-docs.md#commands-for-generating-metadata). #### Самостоятельное размещение dbt Docs v2 Поскольку `dbt docs generate` создаёт автономный статический сайт — одностраничное приложение и индексные файлы Parquet без серверного движка запросов, — вы можете разместить его на любом хостинге статических файлов вместо локального запуска `dbt docs serve`. Во время работы браузер загружает DuckDB-WASM из сети доставки контента (CDN) и напрямую запрашивает данные из Parquet, поэтому для просмотра достаточно сервера статических файлов и исходящего доступа в интернет для подключения к CDN. Сгенерируйте автономный каталог и опубликуйте его на выбранном хостинге: ```shell dbt docs generate --output-dir site ``` Эта команда создаёт каталог `site/` (приложение, ресурсы с хешами в именах файлов и копию индекса), который можно разместить на S3, GitHub Pages, Netlify, GitLab Pages или любом аналогичном хостинге статических файлов. Чтобы обновить документацию, повторно сгенерируйте сайт и опубликуйте его заново. ### dbt Docs (устаревшая версия) dbt Docs предоставляет полезные сведения о ваших проектах dbt v1 или проектах dbt на тарифном плане Developer. Интерфейс позволяет переходить к документации конкретных моделей. Это может выглядеть примерно так: [![Автоматически сгенерированная документация для модели dbt](/img/docs/building-a-dbt-project/testing-and-documentation/f2221dc-Screen_Shot_2018-08-14_at_6.29.55_PM.png?v=2 "Автоматически сгенерированная документация для модели dbt")](#)Автоматически сгенерированная документация для модели dbt Здесь вы видите представление структуры проекта, markdown‑описание модели и список всех колонок модели с документацией. На странице dbt Docs нажмите зелёную кнопку в правом нижнем углу страницы, чтобы развернуть «мини‑карту» вашего DAG. В этой панели отображаются непосредственные родители и потомки модели, которую вы изучаете. [![Открытие мини‑карты DAG](/img/docs/building-a-dbt-project/testing-and-documentation/ec77c45-Screen_Shot_2018-08-14_at_6.31.56_PM.png?v=2 "Открытие мини‑карты DAG")](#)Открытие мини‑карты DAG В этом примере модель `fct_subscription_transactions` имеет только одного прямого родителя. Нажав кнопку **Expand** в правом верхнем углу окна, можно развернуть граф по горизонтали и увидеть полный lineage модели. Этот lineage можно фильтровать с помощью флагов `--select` и `--exclude`, которые соответствуют семантике [model selection syntax](https://docs.getdbt.tech/reference/node-selection/syntax.md). Кроме того, вы можете щёлкнуть правой кнопкой мыши для взаимодействия с DAG, перехода к документации или обмена ссылками на визуализацию графа с коллегами. [![Полный lineage для модели dbt](/img/docs/building-a-dbt-project/testing-and-documentation/ac97fba-Screen_Shot_2018-08-14_at_6.35.14_PM.png?v=2 "Полный lineage для модели dbt")](#)Полный lineage для модели dbt ## Развёртывание сайта документации Без труда публикуйте документацию в Catalog или dbt Docs, чтобы сделать её доступной вашим командам. Security Команда `dbt docs serve` предназначена только для локального или dev‑хостинга сайта документации. Пожалуйста, используйте один из методов, перечисленных в следующем разделе (или аналогичный), чтобы обеспечить безопасный хостинг документации. ### Каталог [Starter](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise +](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе") Catalog автоматически обновляет документацию после каждого запуска задания в среде production или staging, используя сгенерированные метаданные. Это означает, что в нём всегда доступны актуальные результаты для вашего проекта без необходимости ручного развёртывания. Подробнее о том, как Catalog использует метаданные для автоматического обновления документации, см. в разделе [Генерация метаданных](https://docs.getdbt.tech/docs/explore/explore-projects.md#generate-metadata). Чтобы узнать, как развернуть сайт документации, см. раздел [Создание и просмотр документации с помощью dbt](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md). ### dbt Docs (устаревший инструмент) dbt Docs был разработан так, чтобы его было легко разместить в интернете. Сайт является «статическим», то есть для предоставления доступа к документации не нужны «динамические» серверы. Разместить документацию можно несколькими способами: * Разместить на [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) (при необходимости — [с ограничениями доступа по IP-адресам](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html#example-bucket-policies-use-case-3)) * Опубликовать с помощью [Netlify](https://discourse.getdbt.com/t/publishing-dbt-docs-to-netlify/121) * Использовать собственный веб-сервер, например Apache/Nginx * Если вы используете тарифный план dbt Developer, см. раздел [Создание и просмотр документации с помощью dbt](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md?version=1.12#dbt-docs), чтобы узнать, как развернуть сайт документации. Если вы хотите использовать Catalog, чтобы воспользоваться всеми возможностями документации dbt, зарегистрируйтесь для [бесплатного пробного использования dbt](https://www.getdbt.com/signup) или [свяжитесь с нами](https://www.getdbt.com/contact).