Когда вы в последний раз впервые смотрели на хранилище данных? Помните то чувство фрустрации, когда вы не знали, что содержат таблицы 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: Дата выпуска альбома.
Данные
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.
Использование блока 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
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 Павлом Рословцом. Больше материала в нашем сообществе
redfox0
Комментировать таблицы и поля уже стало не модно? И из sql вытаскивать всю информацию и генерировать документацию наверняка можно.
Особенно актуально, когда у тебя сотня пакетов на pl/sql и разработчики начинают уже путаться и писать одинаковый функционал, вместо того, чтобы вызвать уже готовую функцию.
Kahelman
Специально для этого случая придумали describe/comment on команду аналог которой есть во многих DBMS.