[Перевод] Простая документация с dbt: Упрощение документирования хранилищ данных

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

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

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

331a7ee609f1a18c39f7034b5739c9cc.png

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

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

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

version: 2
models:

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

name: album_id
description: >
Уникальный идентификатор для каждого альбома.
tests:

unique


name: album_name
description: >
Название альбома.
name: artist_id
description: >
Уникальный идентификатор исполнителя, связанного с альбомом.



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

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

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

Untitled

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

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

dim_album

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

Схема

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

Данные

album_id

album_name

artist_id

release_date

7ce53109

Thriller

7597cd72aa38

1982–11–20

9ce53109

Back in Black

9775d0e2a709

1980–07–25

a286df30

Dark Side of the Moon

0a55a80cb484

1973–03–01

9ea3ce44

The Joshua Tree

bdb298809422

1987–03–09

be5e8d53

Abbey Road

6f9c026b4133

1969–09–26

{% 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.

Untitled

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

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

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

Untitled

Общий тест на уникальность был применен к столбцу 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

album_id

album_name

artist_id

release_date

7ce53109

Thriller

7597cd72aa38

1982–11–20

9ce53109

Back in Black

9775d0e2a709

1980–07–25

a286df30

Dark Side of the Moon

0a55a80cb484

1973–03–01

9ea3ce44

The Joshua Tree

bdb298809422

1987–03–09

be5e8d53

Abbey Road

6f9c026b4133

1969–09–26

tests

older_album_test

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

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

{% enddocs %}

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

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

© Habrahabr.ru