Документация

Хорошая документация для ваших моделей dbt поможет конечным пользователям находить и понимать наборы данных, которые вы для них создаете. dbt предоставляет способ генерировать документацию для вашего проекта dbt и отображать ее в виде веб-сайта.

dbt Copilot доступен в бета-версии

Используйте dbt Copilot, доступный в бета-версии, чтобы генерировать documentation только в dbt Cloud IDE.

Чтобы использовать dbt Copilot, у вас должна быть активная учетная запись dbt Cloud Enterprise, и вы должны либо согласиться использовать ключ OpenAI от dbt Labs, либо предоставить свой собственный ключ Open AI API. Зарегистрируйтесь здесь или свяжитесь с командой по работе с клиентами, чтобы присоединиться к закрытой бета-версии.

Связанная документация

• Объявление свойств
• Команда dbt docs
• Функция Jinja doc
• Если вы новичок в dbt, мы рекомендуем ознакомиться с нашим руководством по быстрому старту, чтобы создать свой первый проект dbt, включая документацию.

Предполагаемые знания

• Тесты

Обзор

dbt предоставляет способ генерировать документацию для вашего проекта dbt. Документация для вашего проекта включает:

• Информацию о вашем проекте: включая код модели, DAG вашего проекта, любые тесты, которые вы добавили к столбцу, и многое другое.
• Информацию о вашем : включая типы данных столбцов и размеры . Эта информация генерируется путем выполнения запросов к информационной схеме.

Важно, что dbt также предоставляет способ добавления описаний к моделям, столбцам, источникам и многому другому, чтобы дополнительно улучшить вашу документацию.

Добавление описаний в ваш проект

Чтобы добавить описания в ваш проект, используйте ключ description: в тех же файлах, где вы объявляете тесты, например:

models/<filename>.yml

version: 2

models:
  - name: events
    description: Эта таблица содержит события кликов с маркетингового веб-сайта

    columns:
      - name: event_id
        description: Это уникальный идентификатор события
        tests:
          - unique
          - not_null

      - name: user-id
        quote: true
        description: Пользователь, который совершил событие
        tests:
          - not_null

Генерация документации проекта

По умолчанию в dbt Cloud доступен dbt Explorer, доступный в планах Team или Enterprise. Используйте dbt Explorer, чтобы просматривать ресурсы вашего проекта (такие как модели, тесты и метрики), его метаданные и их родословную, чтобы лучше понять его текущее состояние в производстве.

Разработчики dbt Cloud и пользователи dbt Core могут использовать dbt Docs, который генерирует базовую документацию, но не предлагает такую же скорость, метаданные или видимость, как dbt Explorer.

Сгенерируйте документацию для вашего проекта, следуя этим шагам:

1. Запустите dbt docs generate — эта команда сообщает dbt скомпилировать соответствующую информацию о вашем проекте dbt и хранилище в файлы manifest.json и catalog.json соответственно.
2. Убедитесь, что вы создали модели с помощью dbt run, чтобы просмотреть документацию для всех столбцов, а не только тех, которые описаны в вашем проекте.
3. Запустите dbt docs serve, если вы разрабатываете локально, чтобы использовать эти файлы .json для заполнения локального веб-сайта.

Чтобы просмотреть ресурс, его метаданные и какие команды необходимы в dbt Explorer, обратитесь к генерации метаданных для получения более подробной информации.

Часто задаваемые вопросы

Есть ли примеры сайтов с документацией dbt?

Да!

• Учебное руководство по быстрому старту: Вы можете создать свой собственный пример проекта dbt, следуя руководству по быстрому старту
• Jaffle Shop: Демонстрационный проект (тесно связанный с учебным руководством) для вымышленного интернет-магазина (основной исходный код и исходный код с использованием duckdb)
• GitLab: Внутренний проект dbt компании GitLab является открытым исходным кодом и является отличным примером использования dbt в масштабах (исходный код)
• dummy-dbt: Контейнеризированный проект dbt, который заполняет базу данных Sakila в Postgres и заполняет dbt seeds, модели, снимки и тесты. Проект может быть использован для тестирования и экспериментов (исходный код)
• Google Analytics 4: Демонстрационный проект, который преобразует экспорт Google Analytics 4 в BigQuery в различные модели (исходный код, документация)
• Make Open Data: Производственный ELT с тестами, документацией и CI/CD (GHA) о французских открытых данных (жилье, демография, география и т.д.). Может быть использован для обучения с объемными и неоднозначными данными. Приветствуются вклады (исходный код, документация)

Если у вас есть пример проекта, который вы хотите добавить в этот список, предложите правку, нажав Edit this page ниже.

Нужно ли добавлять запись в YAML для столбца, чтобы он появился на сайте документации?

К счастью, нет!

dbt будет анализировать ваш хранилище данных, чтобы сгенерировать список столбцов в каждой связи и сопоставить его со списком столбцов в ваших .yml файлах. Таким образом, любые недокументированные столбцы все равно появятся в вашей документации!

Как писать развернутые объяснения в описаниях?

Если вам нужно больше одного предложения, чтобы объяснить модель, вы можете:

1. Разделить ваше описание на несколько строк, используя >. Внутренние разрывы строк будут удалены, и можно использовать Markdown. Этот метод рекомендуется для простых, одноабзацных описаний:

  version: 2

  models:
  - name: customers
    description: >
      Lorem ipsum **dolor** sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
      quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat.

2. Разделить ваше описание на несколько строк, используя |. Внутренние разрывы строк сохраняются, и можно использовать Markdown. Этот метод рекомендуется для более сложных описаний:

  version: 2

  models:
  - name: customers
    description: |
      ### Lorem ipsum

      * dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      * tempor incididunt ut labore et dolore magna aliqua.

3. Использовать блок docs, чтобы написать описание в отдельном Markdown файле.

Как получить доступ к документации в dbt Explorer?

Если вы используете dbt Cloud для развертывания вашего проекта и у вас есть план Team или Enterprise, вы можете использовать dbt Explorer для просмотра ресурсов вашего проекта (таких как модели, тесты и метрики) и их происхождения данных, чтобы лучше понять его текущее состояние в производстве.

Получите доступ к dbt Explorer в dbt Cloud, нажав на ссылку Explore в навигации. Вы можете предоставить доступ к документации вашего проекта до 5 пользователям с правами только для чтения.

Пользователи плана разработчика dbt Cloud и dbt Core могут использовать dbt Docs, который генерирует базовую документацию, но не предлагает такую же скорость, метаданные или видимость, как dbt Explorer.

Могу ли я документировать что-то кроме моделей, например, источники, семена и снимки?

Да! Вы можете документировать практически все в вашем проекте, используя ключ description:. Ознакомьтесь с документацией по описаниям для получения дополнительной информации!

Использование блоков документации

Синтаксис

Чтобы объявить блок документации, используйте тег jinja docs. Блоки документации могут содержать произвольный markdown, но они должны иметь уникальные имена. Их имена могут содержать заглавные и строчные буквы (A-Z, a-z), цифры (0-9) и подчеркивания (_), но не могут начинаться с цифры.

events.md

{% docs table_events %}

Эта таблица содержит события кликов с маркетингового веб-сайта.

События в этой таблице записываются с помощью Snowplow и передаются в хранилище каждый час. Отслеживаются следующие страницы маркетингового сайта:
 - /
 - /about
 - /team
 - /contact-us

{% enddocs %}

В приведенном выше примере блок документации с именем table_events определен с некоторым описательным содержимым markdown. В имени table_events нет ничего значительного — блоки документации могут быть названы как угодно, если имя содержит только буквенно-цифровые символы и подчеркивания и не начинается с цифры.

Размещение

Использование

Чтобы использовать блок документации, ссылайтесь на него из вашего файла schema.yml с помощью функции doc() вместо строки markdown. Используя приведенные выше примеры, документация table_events может быть включена в файл schema.yml, как показано ниже:

schema.yml

version: 2

models:
  - name: events
    description: '{{ doc("table_events") }}'

    columns:
      - name: event_id
        description: Это уникальный идентификатор события
        tests:
            - unique
            - not_null

В полученной документации '{{ doc("table_events") }}' будет расширено до markdown, определенного в блоке документации table_events.

Установка пользовательского обзора

Доступно только для dbt Docs.

"Обзор", показанный на веб-сайте dbt Docs, можно переопределить, предоставив собственный блок документации с именем __overview__. По умолчанию dbt предоставляет обзор с полезной информацией о самом сайте документации. В зависимости от ваших потребностей, может быть хорошей идеей переопределить этот блок документации с конкретной информацией о вашем корпоративном стиле, ссылками на отчеты или информацией о том, к кому обратиться за помощью. Чтобы переопределить обзор по умолчанию, создайте блок документации, который выглядит следующим образом:

models/overview.md

{% docs __overview__ %}
# Руководство по ежемесячной повторяющейся выручке (MRR).
Этот проект dbt является рабочим примером, демонстрирующим, как моделировать выручку от подписки. **Ознакомьтесь с полным описанием [здесь](https://blog.getdbt.com/modeling-subscription-revenue/),
а также с репозиторием для этого проекта [здесь](https://github.com/dbt-labs/mrr-playbook/).**
...

{% enddocs %}

Пользовательские обзоры на уровне проекта

Доступно только для dbt Docs.

Вы можете установить разные обзоры для каждого проекта/пакета dbt, включенного в ваш сайт документации, создав блок документации с именем __[project_name]__. Например, чтобы определить пользовательские страницы обзора, которые появляются, когда пользователь переходит в пакет dbt_utils или snowplow:

models/overview.md

{% docs __dbt_utils__ %}
# Утилитарные макросы
Наш проект dbt активно использует этот набор утилитарных макросов, особенно:
- `surrogate_key`
- `test_equality`
- `pivot`
{% enddocs %}

{% docs __snowplow__ %}
# Сессии Snowplow
Наша организация использует этот пакет преобразований для объединения событий Snowplow в просмотры страниц и сессии.
{% enddocs %}

Навигация по сайту документации

Используйте dbt Explorer для более богатого и интерактивного опыта понимания ресурсов и родословной вашего проекта. Доступно в планах Team или Enterprise.

Для получения дополнительных сведений о том, как исследовать вашу родословную и навигировать по вашим ресурсам, обратитесь к dbt Explorer.

Пример деталей ресурса

 Для пользователей dbt Docs

Если вы используете интерфейс dbt Docs, вы можете перейти к документации для конкретной модели. Это может выглядеть примерно так:

Автоматически сгенерированная документация для модели dbt

Здесь вы можете увидеть представление структуры проекта, описание модели в формате markdown и список всех столбцов (с документацией) в модели.

На странице dbt Docs вы можете нажать зеленую кнопку в нижнем правом углу веб-страницы, чтобы развернуть "мини-карту" вашего DAG. Эта панель (показана ниже) отобразит непосредственных родителей и детей модели, которую вы исследуете.

Открытие мини-карты DAG

В этом примере модель fct_subscription_transactions имеет только одного прямого родителя. Нажав кнопку "Развернуть" в правом верхнем углу окна, мы можем повернуть график горизонтально и просмотреть полную родословную для нашей модели. Эта родословная может быть отфильтрована с использованием флагов --select и --exclude, которые соответствуют семантике синтаксиса выбора модели. Кроме того, вы можете щелкнуть правой кнопкой мыши, чтобы взаимодействовать с DAG, перейти к документации или поделиться ссылками на вашу визуализацию графа с вашими коллегами.

Полная родословная для модели dbt

Развертывание сайта документации

С помощью dbt Cloud используйте dbt Explorer, который автоматически получает обновления метаданных после каждого выполнения задания в производственной или промежуточной среде развертывания, чтобы всегда иметь последние результаты для вашего проекта — это означает, что он всегда автоматически обновляется после каждого выполнения задания.

Безопасность

Команда dbt docs serve предназначена только для локального/разработческого хостинга сайта документации. Пожалуйста, используйте один из перечисленных ниже методов (или аналогичный), чтобы убедиться, что ваш сайт документации размещен безопасно!

Для пользователей dbt Docs

Веб-сайт документации dbt был создан, чтобы его было легко разместить в интернете. Сайт является "статическим", что означает, что вам не нужны "динамические" серверы для обслуживания документации. Вы можете разместить вашу документацию несколькими способами:

• Используйте dbt Cloud's стандартный опыт работы с документацией с dbt Explorer.
• Разместите на Amazon S3 (опционально с ограничениями доступа по IP)
• Опубликуйте с помощью Netlify
• Используйте ваш собственный веб-сервер, такой как Apache/Nginx