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

Когда вы в последний раз впервые смотрели на хранилище данных? Помните то чувство фрустрации, когда вы не знали, что содержат таблицы 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 Павлом Рословцом. Больше материала в нашем сообществе