Перейти к основному содержимому

Остальная часть проекта

Обзор структуры проекта​

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

models
├── marts
│ ├── customers.sql
│ ├── customers.yml
│ ├── order_items.sql
│ ├── order_items.yml
│ ├── orders.sql
│ ├── orders.yml
│ └── ...
└── staging
├── __sources.yml
├── stg_customers.sql
├── stg_customers.yml
├── stg_orders.sql
├── stg_orders.yml
└── ...

Подробности о YAML​

При организации ваших YAML конфигурационных файлов в dbt проекте, вы должны сбалансировать централизацию и размер файлов, чтобы сделать конкретные конфигурации как можно более легкими для поиска. Важно отметить, что в то время как YAML файлы верхнего уровня (dbt_project.yml, packages.yml) должны иметь определенные имена и находиться в определенных местах, файлы, содержащие ваши словари sources и models, могут быть названы, расположены и организованы как угодно. Здесь важны внутренние содержимое. Таким образом, мы изложим нашу основную рекомендацию, а также плюсы и минусы популярной альтернативы. Как и во многих других аспектах организации вашего dbt проекта, здесь наиболее важны последовательность, ясное намерение и тщательная документация о том, как и почему вы делаете то, что делаете.

  • ✅ Конфигурация на уровне папки. Как в примере выше, создавайте файл _[directory]__models.yml для каждой папки в каталоге models, который настраивает все модели в этой папке. Для staging‑папок также добавляйте файл _[directory]__sources.yml на каждую папку.
    • Ведущее подчёркивание гарантирует, что ваши YAML‑файлы будут сортироваться в начало каждой папки, что упрощает их отделение от файлов моделей.
    • YAML‑файлам не требуются уникальные имена так же строго, как SQL‑файлам моделей, однако включение имени папки (вместо простого _sources.yml в каждой папке) позволяет быстрее находить нужный файл через fuzzy‑поиск.
    • За последние годы мы рекомендовали несколько разных соглашений об именовании, в том числе совсем недавно называли эти файлы schema.yml. Мы упростили рекомендации и советуем называть файлы просто по словарю YAML, который они содержат.
    • Если вы используете doc blocks в своём проекте, мы рекомендуем придерживаться того же подхода и создавать markdown‑файл _[directory]__docs.md для каждой папки, содержащий все doc blocks для моделей в этой папке.
  • ❌ Конфигурация на уровне проекта. Некоторые помещают все YAML‑описания источников и моделей в один файл. Технически это возможно и действительно упрощает понимание того, в каком файле находится нужная конфигурация (поскольку файл всего один), но при этом становится гораздо сложнее находить конкретные настройки внутри этого файла. Мы рекомендуем находить баланс между этими двумя соображениями.
  • ⚠️ Конфигурация на уровне модели. С другой стороны спектра, некоторые предпочитают создавать по одному YAML‑файлу на модель. Это менее проблематично, чем один монолитный файл, так как можно быстро искать файлы, точно знать, где находятся конкретные настройки, видеть модели без конфигураций (а значит, без тестов), просто глядя на дерево файлов, и получать ряд других преимуществ. Однако, по нашему мнению, дополнительное количество файлов, вкладок и окон, которые приходится создавать, копировать, вставлять, закрывать, открывать и администрировать, приводит к несколько более медленному процессу разработки, и этот недостаток перевешивает преимущества. Для большинства проектов конфигурация на уровне папки — самый сбалансированный подход, но если у вас есть веские причины использовать конфигурацию на уровне модели, существуют отличные проекты, которые успешно следуют этой парадигме.
  • ✅ Каскадирование конфигураций. Используйте dbt_project.yml для задания конфигураций по умолчанию на уровне папок. Применяйте хорошо организованную структуру каталогов, которую мы уже создали, чтобы определить базовые схемы и материализации, а затем используйте приоритет областей видимости dbt для задания отклонений от этих значений. Например, как показано ниже, задайте materialization table по умолчанию для marts, определите отдельные схемы для разных подпапок, а модели, которым требуется materialization incremental, можно настроить на уровне конкретной модели.
# dbt_project.yml

models:
jaffle_shop:
staging:
+materialized: view
+schema: staging
intermediate:
+materialized: view
+schema: intermediate
marts:
+materialized: table
+schema: marts

Обратитесь к разделу Сопоставление папок проекта со схемами хранилища, чтобы понять, как значения +schema определяют схемы в хранилище в средах разработки и продакшена.

Задайте настройки по умолчанию.

Одно из многочисленных преимуществ такого последовательного подхода к структуре проекта — возможность каскадно применять настройки по умолчанию. Тщательная организация папок и определение конфигурации на их уровне везде, где это возможно, избавляют нас от необходимости задавать такие настройки, как схема и материализация, в каждой отдельной модели (что совсем не соответствует принципу DRY!) — нам нужно настраивать только исключения из общих правил. Теги — ещё одна область, где действует этот принцип. Многие новички в dbt полагаются на теги вместо строгой структуры папок и быстро оказываются в ситуации, когда каждой модели требуется тег. Это создаёт ненужную сложность. Мы хотим использовать папки как основной механизм выбора и группировки, а теги — для определения групп, которые являются исключениями. Выбор на основе папок, например **dbt build --select marts.marketing, гораздо проще, чем назначать тег каждой модели, связанной с маркетингом, надеяться, что все разработчики не забудут добавить этот тег в новые модели, и использовать dbt build --select tag:marketing.

Определение групп​

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

Группы определяются в файлах .yml внутри ключа groups:. В версии 1.10 и выше можно добавить description и конфигурацию meta, чтобы указать дополнительную информацию о группе.

(Версии dbt: v1.10 и новее)
models/marts/finance/finance.yml
groups:
- name: finance
description: "All finance-related models owned by the Finance team." # optional
owner:
# 'name' or 'email' is required; additional properties will no longer be allowed in a future release
email: finance@jaffleshop.com
config:
meta: # optional
data_owner: Finance team
cost_center: finance
data_classification: sensitive

Дополнительную информацию об использовании групп см. в разделе Добавление групп в ваш DAG.

Как мы используем другие папки​

jaffle_shop
├── analyses
├── data-tests
├── macros
│ └── cents_to_dollars.sql
├── seeds
│ └── jaffle-data
│ ├── raw_customers.csv
│ ├── raw_orders.csv
│ └── ...
└── snapshots

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

  • ✅ seeds для справочных таблиц. Самый распространённый сценарий использования seeds — загрузка справочных таблиц, которые полезны для моделирования, но отсутствуют в исходных системах: например, таблиц соответствия почтовых индексов штатам или UTM-параметров маркетинговым кампаниям. В этом примере проекта файлы seeds находятся в seeds/jaffle-data/ и позволяют заполнить схему raw для локальной разработки, если включён параметр load_source_data.
  • ❌ seeds для загрузки исходных данных. Не используйте seeds для загрузки данных из исходной системы в хранилище. Если данные существуют в системе, к которой у вас есть доступ, их следует загружать в область исходных данных вашего хранилища с помощью специализированного инструмента EL. dbt предназначен для работы с данными в хранилище, а не для их загрузки.
  • ✅ analyses для хранения аудиторских запросов. Папка analyses позволяет хранить любые запросы, в которых вы хотите использовать Jinja и которые хотите отслеживать в системе контроля версий, но не создавать на их основе модели в хранилище. Возможности здесь безграничны, но при настройке проектов в dbt Labs мы чаще всего используем эту папку для хранения запросов, задействующих пакет audit helper. Этот пакет чрезвычайно полезен для поиска расхождений в результатах при переносе логики из другой системы в dbt.
  • ✅ tests для одновременного тестирования нескольких конкретных таблиц. По мере развития тестов dbt необходимость писать единичные тесты (singular tests) возникала всё реже. Они очень полезны для отработки логики тестирования, но чаще всего вы либо переносите эту логику в собственные универсальные тесты (generic tests), либо находите готовый тест под свои задачи среди постоянно растущего множества пакетов dbt (дополнительные тесты из dbt-utils и dbt-expectations охватывают практически любые ситуации). Однако единичные тесты по-прежнему особенно удобны для гибкого тестирования сценариев, в которых участвуют несколько конкретных моделей. Если вы знакомы с разницей между модульными тестами и интеграционными тестами в разработке программного обеспечения, то можете аналогичным образом рассматривать универсальные и единичные тесты. Если вам нужно проверить результаты взаимодействия нескольких конкретных моделей или связи между ними, единичный тест, скорее всего, будет самым быстрым способом точно выразить вашу логику.
  • ✅ snapshots для создания записей медленно изменяющегося измерения типа 2 на основе исходных данных типа 1 (обновляемых с перезаписью предыдущих значений). Эта тема подробно рассмотрена в документации dbt. В отличие от остальных перечисленных папок, у этой папки более чётко определённое назначение; её рассмотрение выходит за рамки этого руководства, но она упомянута для полноты картины.
  • ✅ macros для применения принципа DRY к преобразованиям, которые вы выполняете многократно. Как и в случае со снимками, подробное рассмотрение макросов выходит за рамки этого руководства, и эта тема хорошо раскрыта в другом разделе. Однако одна важная рекомендация, связанная со структурой проекта, — документируйте свои макросы. Мы рекомендуем создать файл _macros.yml и описывать в нём назначение и аргументы макросов, как только они будут готовы к использованию.

Разделение проекта​

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

Mesh позволяет организациям управлять сложностью, связывая несколько dbt‑проектов, вместо того чтобы полагаться на один большой монолитный проект. Такой подход разработан для ускорения разработки при одновременном сохранении управляемости и стандартов (governance).

По мере того, как разделение монолитных dbt проектов на более мелкие, связанные проекты, возможно, в рамках современного моно-репозитория становится проще, сценарии, которые мы в настоящее время не рекомендуем, могут вскоре стать осуществимыми. Так что следите за обновлениями!

  • ✅ Бизнес‑группы или подразделения. Концептуальное разделение внутри проекта — основная причина для его декомпозиции. Это позволяет бизнес‑доменам владеть собственными дата‑продуктами и при этом продолжать совместную работу с использованием Mesh. Подробнее о Mesh см. в разделе FAQ по Mesh.
  • ✅ Управление данными (data governance). Структурные и организационные требования — такие как управление данными и безопасность — относятся к немногим действительно оправданным причинам для разделения проекта. Например, если вы работаете в медицинской компании, где лишь небольшая команда имеет доступ к сырым данным с PII, может потребоваться вынести staging‑модели в отдельные проекты, чтобы сохранить эти политики. В таком случае staging‑проект импортируется в проект, который строится поверх этих моделей, в виде приватного пакета.
  • ✅ Размер проекта. В какой‑то момент проект может вырасти до такого масштаба, что количество моделей начнёт негативно влиять на удобство разработки. Если у вас тысячи моделей, имеет смысл найти способ разделить проект.
  • ❌ Сценарии ML vs отчётность. Аналогично предыдущему пункту, распространённая идея — разделять проект по сценариям использования, в частности между классической BI‑аналитикой и ML‑функциональностью. Мы рекомендуем пока этого избегать. Как и выше, одна из базовых целей внедрения dbt — создание единого источника истины в организации. Функциональность, которую вы предоставляете командам data science, должна строиться на тех же marts и метриках, что и отчёты для руководящих дашбордов.

Заключительные соображения​

В целом, последовательность важнее, чем любые из этих конкретных соглашений. По мере роста вашего проекта и углубления вашего опыта с dbt, вы, несомненно, найдете аспекты вышеуказанной структуры, которые захотите изменить. Хотя мы рекомендуем этот подход для большинства проектов, каждая организация уникальна! Единственный догматический совет, который мы здесь дадим, заключается в том, что когда вы находите аспекты вышеуказанной структуры, которые хотите изменить, тщательно обдумайте свои причины и задокументируйте для вашей команды как и почему вы отклоняетесь от этих соглашений. В этой связи мы настоятельно рекомендуем вам форкнуть это руководство и добавить его в README вашего проекта, вики или документацию, чтобы вы могли быстро создать и настроить эти артефакты.

Наконец, мы подчеркиваем, что это руководство является живым документом! Оно, безусловно, будет изменяться и расти по мере эволюции dbt и dbt Labs. Мы приглашаем вас присоединиться — обсуждать, комментировать и вносить предложения по изменениям или новым элементам для освещения.

Нашли ошибку?

0
Loading