Возможности документации в dbt

dbt — это удобный инструмент не только для трансформации данных, но и для документирования хранилища. В dbt реализована концепция docs as a code, в рамках которой вы описываете объекты в коде, а на основе кода формируется удобная и интерактивная документация.

Документация в браузере

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

Обратите внимание на возможность просмотра объектов вашего dbt проекта в разрезе баз данных и в разрезе групп. Дополнительно, реализован поиск по моделям.

При нажатии на синюю кнопку внизу справа, откроется графа зависимостей моделей.

Чтобы определить связи между таблицами требуется воспользоваться в SQL модели конструкцией ref.

В этом примере прописана ссылка на модель dbt – users:

Если нажать на синюю кнопку справа внизу, находясь в описании конкретной модели, будет показан data lineage этой модели – от чего он зависит и какие модели зависят от нее.

Описание объектов

В dbt для всех типов объектов документация фиксируется в одном только теге – description.

В нем вы описываете бизнес-логику объекта. Доступно минимальное форматирование описания с помощью Markdown.

Description можно указывать для следующих объектов dbt:

У модели можно добавлять описание у самой модели, так и у ее столбцов.

У singular tests (тесты как SQL-запросы):

У generic tests (тесты как макросы) описание указывается там же, где указывается generic test – в конфигах модели либо у самой модели, либо у ее столбца.

Продвинутые функции

Если описание вашей таблицы слишком объемное, записывать его в тег description может показаться не таким изящным выходом. Для подобных ситуаций можно использовать doc-функцию, которая представляет собой что-то вроде макроса (очень схожий синтаксис) и в рамках которой может записывать множество строк документации.

Также с помощью данной функции можно переиспользовать документацию для схожих объектов.

Пример doc-функции:

Использование doc-функции.

Вы можете указывать ссылку на другую модель непосредственно в документации. Для нахождения ссылки модели сформируйте через команды dbt docs generate и serve веб-сайт, найдите нужную вам модель и скопируйте ссылку в браузере, не копируя все до порта.

Копировать только

Затем можете вставить в описание другой модели эту ссылку.

Обновление документации и деплой

Документация в dbt не обновляется автоматически, если вы внесете какие-либо изменения в ваш проект. Потребуется снова запустить команду dbt docs generate. Поэтому правильнее было бы поставить выполнение данной команды на регламент. Или не забывать обновлять после внесения изменений на prod.

dbt Docs представляет собой файлы для веб-сайта. Их можно с легкостью хостить на вашем выделенном веб-сервере Apache или хостить в GitHub Pages.

Наш менеджер свяжется с вами для предоставления бесплатного доступа и презентует наш сервис