Когда вы в последний раз впервые смотрели на хранилище данных? Помните то чувство фрустрации, когда вы не знали, что содержат таблицы orders_final_v1? Или как отличить user_uuid от user_id? Любой специалист по данным может понять эти ощущения.

К счастью, dbt (Data Build Tool) значительно упростил задачу документирования хранилищ данных. Все, что нужно сделать, это включить описание наших таблиц и колонок в YAML-файл схемы. Затем вся информация собирается в аккуратный HTML-файл.

Данная статья это перевод с английского с некоторыми адаптациями. Перевод сделан НЕшколой для инженеров Inzhenerka.Tech совместно с автором симулятора по DWH на dbt Павлом Рословцом. Больше материала в нашем сообществе

Документирование вашего хранилища данных (DWH)

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

Начнем с файла models/schema.yml. Этот файл будет содержать всю информацию о ваших таблицах. Например, рассмотрим следующую документацию для таблицы dim_album:

version: 2

models:
- name: dim_album
  description: >
    The dim_album table is a dimensional table in the music database that 
    contains information about albums. It serves as a reference table 
    for the fact tables in the database and provides details about 
    various albums.
  columns:
  - name: album_id
    description: > 
      A unique identifier for each album
    tests:
      - unique
  - name: album_name
    description: >
      The name of the album
  - name: artist_id
    description: > 
      The unique identifier of the artist associated with the album

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

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

После сохранения указанного выше YAML-файла, выполните команду dbt docs generate. Эта команда сгенерирует документацию на основе описания, заданного в файле schema.yml.

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

Мы можем поднять документацию на новый уровень, используя блоки docs. Это позволяет нам использовать файл Markdown с Jinja-скриптами для создания еще более детализированного и всеобъемлющего документа

dim_album

Описание: Таблица dim_album является размерной таблицей в музыкальной базе данных, которая содержит информацию об альбомах. Она служит справочной таблицей для фактографических таблиц в базе данных и предоставляет подробные сведения о различных альбомах.

Схема

album_id: Уникальный идентификатор для каждого альбома.
album_name: Название альбома.
artist_id: Уникальный идентификатор исполнителя, связанного с альбомом.
release_date: Дата выпуска альбома.

Данные

{% enddocs %}

version: 2

models:
- name: dim_album
  description: "{{ doc('dim_album') }}"
  columns:
  - name: album_id
    description: > 
      A unique identifier for each album
    tests:
      - unique
  - name: album_name
    description: >
      The name of the album
  - name: artist_id
    description: > 
      The unique identifier of the artist associated 
      with the album
  - name: release_date
    description: >
      The date when the album was released

Затем мы ссылаемся на файл models/docs.md в формате Markdown, используя Jinja в файле схемы YAML:

Заменяем описание модели на Jinja-заполнитель {% raw %} {{ doc('dim_album') }}.

Этот подход позволяет создавать документацию с полной гибкостью, которую предоставляет файл в формате Markdown.

Использование блока docs для отображения документации таблицы dim_album

Что насчет тестов?

Всякий раз, когда в файле схемы YAML применяется общий тест к столбцу, он будет отображаться в документации под соответствующим столбцом.

Общий тест на уникальность был применен к столбцу album_id. Он настроен в файле схемы YAML и отображается с помощью dbt docs serve.

Подобно общим тестам, индивидуальные тесты представляют собой настраиваемые SQL-запросы, которые выполняются для наших моделей dbt. Они хранятся в папке tests и выполняются вместе с общими тестами.

Одним из важных аспектов документации является описание тестов, которые вы написали для проверки ваших моделей данных. В настоящее время dbt создаёт страницу документации для индивидуальных тестов. Эта страница покажет SQL-запрос, лежащий в основе индивидуального теста, а также модель, которая тестируется, и её зависимости.

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

{% docs dim_album %}

dim_album

Описание: Таблица dim_album является размерной таблицей в музыкальной базе данных, которая содержит информацию об альбомах. Она служит справочной таблицей для фактографических таблиц в базе данных и предоставляет подробные сведения о различных альбомах.

Schema

album_id: Уникальный идентификатор для каждого альбома.
album_name: Название альбома.
artist_id: Уникальный идентификатор исполнителя, связанного с альбомом.
release_date: Дата выпуска альбома.

Data Sample

tests

older_album_test

Таблица dim_album содержит данные об альбомах, выпущенных в 1950 году или позже. Тест вызывает тревогу всякий раз, когда обнаруживается хотя бы один альбом, дата выпуска которого предшествует 1950 году.

Для получения дополнительной информации посетите ссылку.

{% enddocs %}

Вот и всё! Результатом является страница документации вашей модели, которая перечисляет как общие, так и индивидуальные тесты модели. Всегда полезно добавить запрос, который поможет читателю определить и исправить ошибку, обнаруженную тестом. И последнее, но не менее важное: не забывайте использовать ясный и лаконичный язык, когда это возможно. Удачных запросов!

Данная статья это перевод с английского с некоторыми адаптациями. Перевод сделан НЕшколой для инженеров Inzhenerka.Tech совместно с автором симулятора по DWH на dbt Павлом Рословцом. Больше материала в нашем сообществе