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

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

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

models
├── intermediate
│   └── finance
│       ├── _int_finance__models.yml
│       └── int_payments_pivoted_to_orders.sql
├── marts
│   ├── finance
│   │   ├── _finance__models.yml
│   │   ├── orders.sql
│   │   └── payments.sql
│   └── marketing
│       ├── _marketing__models.yml
│       └── customers.sql
├── staging
│   ├── jaffle_shop
│   │   ├── _jaffle_shop__docs.md
│   │   ├── _jaffle_shop__models.yml
│   │   ├── _jaffle_shop__sources.yml
│   │   ├── base
│   │   │   ├── base_jaffle_shop__customers.sql
│   │   │   └── base_jaffle_shop__deleted_customers.sql
│   │   ├── stg_jaffle_shop__customers.sql
│   │   └── stg_jaffle_shop__orders.sql
│   └── stripe
│       ├── _stripe__models.yml
│       ├── _stripe__sources.yml
│       └── stg_stripe__payments.sql
└── utilities
    └── all_dates.sql

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

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

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

-- dbt_project.yml

models:
  jaffle_shop:
    staging:
      +materialized: view
    intermediate:
      +materialized: ephemeral
    marts:
      +materialized: table
      finance:
        +schema: finance
      marketing:
        +schema: marketing

Определите ваши значения по умолчанию.

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

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

jaffle_shop
├── analyses
├── seeds
│   └── employees.csv
├── macros
│   ├── _macros.yml
│   └── cents_to_dollars.sql
├── snapshots
└── tests
└── assert_positive_value_for_total_amount.sql

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

• ✅ seeds для таблиц поиска. Наиболее распространенный случай использования seeds — это загрузка таблиц поиска, которые полезны для моделирования, но не существуют в каких-либо исходных системах — подумайте о сопоставлении почтовых индексов с штатами или UTM параметров с маркетинговыми кампаниями. В этом примере проекта у нас есть небольшой seed, который сопоставляет наших сотрудников с их customer_id, чтобы мы могли обрабатывать их покупки с особой логикой.
• ❌ seeds для загрузки исходных данных. Не используйте seeds для загрузки данных из исходной системы в ваш склад данных. Если они существуют в системе, к которой у вас есть доступ, вы должны загружать их с помощью правильного инструмента EL в область необработанных данных вашего склада. dbt предназначен для работы с данными в складе, а не как инструмент загрузки данных.
• ✅ analyses для хранения аудиторских запросов. Папка analyses позволяет вам хранить любые запросы, которые вы хотите использовать с Jinja и контролировать версию, но не строить в модели в вашем складе. Здесь есть безграничные возможности, но наиболее распространенный случай использования, когда мы настраиваем проекты в dbt Labs, — это хранение запросов, которые используют пакет audit helper. Этот пакет невероятно полезен для поиска расхождений в выводе при миграции логики из другой системы в dbt.
• ✅ tests для тестирования нескольких конкретных таблиц одновременно. По мере эволюции тестов dbt, написание отдельных тестов становится все менее необходимым. Это чрезвычайно полезно для разработки логики тестов, но чаще всего вы обнаружите, что либо мигрируете эту логику в свои собственные пользовательские общие тесты, либо находите предустановленный тест, который соответствует вашим потребностям из постоянно расширяющейся вселенной пакетов dbt (между дополнительными тестами в dbt-utils и dbt-expectations почти любая ситуация покрыта). Однако одна область, где отдельные тесты все еще блестят, — это гибкое тестирование вещей, которые требуют разнообразия конкретных моделей. Если вы знакомы с разницей между модульными тестами и интеграционными тестами в программной инженерии, вы можете думать о общих и отдельных тестах аналогичным образом. Если вам нужно протестировать результаты того, как несколько конкретных моделей взаимодействуют или связаны друг с другом, отдельный тест, вероятно, будет самым быстрым способом закрепить вашу логику.
• ✅ snapshots для создания записей Типа 2 медленно изменяющихся измерений из Типа 1 (разрушающе обновляемых) исходных данных. Это подробно описано в документации dbt, в отличие от этих других папок, имеет более определенную цель и выходит за рамки этого руководства, но упоминается для полноты.
• ✅ macros для упрощения повторяющихся преобразований. Как и в случае со снимками, полное погружение в макросы выходит за рамки этого руководства и хорошо освещено в других местах, но одна важная рекомендация, связанная со структурой, — это документировать ваши макросы. Мы рекомендуем создать _macros.yml и документировать цель и аргументы для ваших макросов, когда они готовы к использованию.

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

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

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

• ✅ Бизнес-группы или отделы. Концептуальные разделения внутри проекта являются основной причиной для разделения вашего проекта. Это позволяет вашим бизнес-доменам владеть своими собственными данными и все еще сотрудничать, используя dbt Mesh. Для получения дополнительной информации о dbt Mesh, пожалуйста, обратитесь к нашим dbt Mesh FAQs.
• ✅ Управление данными. Структурные, организационные потребности — такие как управление данными и безопасность — являются одной из немногих стоящих причин для разделения проекта. Если, например, вы работаете в компании здравоохранения с небольшой командой, имеющей доступ к необработанным данным с PII, вам может потребоваться выделить ваши модели staging в отдельные проекты, чтобы сохранить эти политики. В этом случае вы бы импортировали ваш проект staging в проект, который строится на этих моделях staging, как частный пакет.
• ✅ Размер проекта. В какой-то момент ваш проект может вырасти до такого количества моделей, что это просто станет неосуществимым для разработки. Если у вас 1000 моделей, имеет смысл найти способ разделить ваш проект.
• ❌ Использование для ML и отчетности. Аналогично предыдущему пункту, разделение проекта на основе различных случаев использования, особенно более стандартных BI против ML функций, является распространенной идеей. Мы склонны не рекомендовать это на данный момент. Как и в предыдущем пункте, основная цель внедрения dbt — создать единый источник правды в вашей организации. Функции, которые вы предоставляете вашим командам по анализу данных, должны исходить из тех же marts и метрик, которые обслуживают отчеты на исполнительных панелях.

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

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

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