Конфигурации, свойства, что это такое?

Ресурсы в вашем проекте — модели, снимки, семена, тесты и другие — могут иметь ряд объявленных свойств. Ресурсы также могут определять конфигурации, которые являются особым видом свойств, предоставляющим дополнительные возможности. В чем различие?

• Свойства объявляются для ресурсов по одному в файлах properties.yml. Конфигурации могут быть определены там же, вложенные в свойство config. Они также могут быть заданы по одному через макрос config() (прямо в .sql файлах) и для многих ресурсов одновременно в dbt_project.yml.
• Поскольку конфигурации могут быть заданы в нескольких местах, они также применяются иерархически. Индивидуальный ресурс может унаследовать или переопределить конфигурации, заданные в другом месте.
• Вы можете выбирать ресурсы на основе их значений конфигурации, используя метод выбора config:, но не на основе значений свойств, не являющихся конфигурациями.
• Существуют немного разные соглашения об именах для свойств и конфигураций в зависимости от типа файла. Обратитесь к соглашению об именах для получения более подробной информации.

Правило большого пальца: свойства объявляют вещи о ресурсах вашего проекта; конфигурации делают дополнительный шаг, указывая dbt как строить эти ресурсы в вашем хранилище. Это в целом верно, но не всегда, поэтому всегда полезно проверять!

Например, вы можете использовать свойства ресурса для:

• Описания моделей, снимков, файлов семян и их столбцов
• Утверждения "истин" о модели в форме тестов данных, например, "этот столбец id уникален"
• Определения указателей на существующие таблицы, содержащие сырые данные, в форме источников и утверждения ожидаемой "свежести" этих сырых данных
• Определения официальных downstream-использований ваших моделей данных в форме экспозиций

В то время как вы можете использовать конфигурации для:

• Изменения способа материализации модели (, , инкрементально и т.д.)
• Объявления, где будет создано семя в базе данных (<database>.<schema>.<alias>)
• Объявления, следует ли ресурсу сохранять свои описания в виде комментариев в базе данных
• Применения тегов и "мета" свойств

Где я могу определить конфигурации?

В зависимости от типа ресурса, конфигурации могут быть определены в проекте dbt, а также в установленном пакете с помощью:

Наследование конфигураций

Наиболее специфичная конфигурация всегда имеет приоритет. Это обычно следует порядку выше: блок config() в файле --> свойства, определенные в .yml файле --> конфигурация, определенная в файле проекта.

Примечание - Генерические тесты данных работают немного иначе, когда дело касается специфичности. См. конфигурации тестов.

Внутри файла проекта конфигурации также применяются иерархически. Наиболее специфичная конфигурация всегда имеет приоритет. В файле проекта, например, конфигурации, примененные к поддиректории marketing, будут иметь приоритет над конфигурациями, примененными ко всему проекту jaffle_shop. Чтобы применить конфигурацию к модели или директории моделей, определите путь ресурса как вложенные ключи словаря.

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

Комбинирование конфигураций

Большинство конфигураций "замещаются" при иерархическом применении. Всякий раз, когда доступно более специфичное значение, оно полностью заменяет менее специфичное значение. Обратите внимание, что несколько конфигураций имеют другое поведение при слиянии:

• tags являются аддитивными. Если у модели есть некоторые теги, настроенные в dbt_project.yml, и больше тегов, примененных в ее .sql файле, конечный набор тегов будет включать все из них.
• Словари meta объединяются (более специфичная пара ключ-значение заменяет менее специфичное значение с тем же ключом)
• pre-hook и post-hook также являются аддитивными.

Где я могу определить свойства?

В dbt вы можете использовать файлы properties.yml для определения свойств ресурсов. Вы можете объявлять свойства в .yml файлах в той же директории, что и ваши ресурсы. Вы можете назвать эти файлы как угодно и вложить их произвольно в подкаталоги в каждой директории.

Мы настоятельно рекомендуем определять свойства в выделенных путях рядом с ресурсами, которые они описывают.

к сведению

файлы schema.yml

Предыдущие версии документации называли их файлами schema.yml — мы отошли от этой терминологии, так как слово schema используется для обозначения других вещей при разговоре о базах данных, и люди часто думали, что вы должны называть эти файлы schema.yml.

Вместо этого мы теперь называем эти файлы файлами properties.yml. (Конечно, вы все еще можете называть свои файлы schema.yml)

Какие свойства не являются также конфигурациями?

В dbt вы можете определять конфигурации узлов в файлах properties.yml, в дополнение к блокам config() и файлу dbt_project.yml. Однако некоторые специальные свойства могут быть определены только в .yml файле, и вы не можете настроить их с помощью блоков config() или файла dbt_project.yml:

Некоторые свойства являются особенными, потому что:

• У них уникальный контекст рендеринга Jinja
• Они создают новые ресурсы проекта
• Они не имеют смысла как иерархическая конфигурация
• Это старые свойства, которые еще не были переопределены как конфигурации

Эти свойства:

• description
• tests
• docs
• columns
• quote
• source свойства (например, loaded_at_field, freshness)
• exposure свойства (например, type, maturity)
• macro свойства (например, arguments)

Пример

Вот пример, который определяет как sources, так и models для проекта:

models/jaffle_shop.yml

version: 2

sources:
  - name: raw_jaffle_shop
    description: Копия базы данных postgres, используемой для работы приложения jaffle_shop.
    tables:
      - name: customers
        columns:
          - name: id
            description: Первичный ключ таблицы
            tests:
              - unique
              - not_null

      - name: orders
        columns:
          - name: id
            description: Первичный ключ таблицы
            tests:
              - unique
              - not_null

          - name: user_id
            description: Внешний ключ к customers

          - name: status
            tests:
              - accepted_values:
                  values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']


models:
  - name: stg_jaffle_shop__customers
    config:
      tags: ['pii']
    columns:
      - name: customer_id
        tests:
          - unique
          - not_null

  - name: stg_jaffle_shop__orders
    config:
      materialized: view
    columns:
      - name: order_id
        tests:
          - unique
          - not_null
      - name: status
        tests:
          - accepted_values:
              values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
              config:
                severity: warn

Связанная документация

Вы можете найти исчерпывающий список каждого поддерживаемого свойства и конфигурации, разбитый по типу ресурса:

• Свойства моделей и конфигурации
• Свойства источников и конфигурации
• Свойства семян и конфигурации
• Свойства снимков
• Свойства анализов
• Свойства макросов
• Свойства экспозиций

Часто задаваемые вопросы

Нужно ли называть мой файл `.yml`, содержащий тесты и описания, `schema.yml`?

Нет! Вы можете назвать этот файл как угодно (включая whatever_you_want.yml), при условии, что:

• Файл находится в вашем каталоге models/¹
• Файл имеет расширение .yml

Посмотрите документацию для получения дополнительной информации.

¹Если вы объявляете свойства для seeds, snapshots или macros, вы также можете разместить этот файл в соответствующем каталоге — seeds/, snapshots/ и macros/ соответственно.

Если я могу называть эти файлы как угодно, как мне их назвать?

Это зависит от вас! Вот несколько вариантов:

• Используйте существующую терминологию: schema.yml (хотя это может затруднить поиск нужного файла со временем)
• Используйте то же имя, что и у вашего каталога (при условии, что вы используете разумные имена для ваших каталогов)
• Если вы тестируете и документируете одну модель (или seed, snapshot, macro и т.д.) на файл, вы можете дать ему то же имя, что и у модели (или seed, snapshot, macro и т.д.)

Выберите то, что подходит вашей команде. У нас есть больше рекомендаций в нашем руководстве по структурированию проектов dbt.

Следует ли использовать отдельные файлы для объявления свойств ресурсов или один большой файл?

Это зависит от вас:

• Некоторые считают полезным иметь один файл на каждую модель (или источник / снимок / семя и т.д.)
• Другие считают полезным иметь один файл на каталог, документируя и тестируя несколько моделей в одном файле

Выберите то, что подходит вашей команде. У нас есть больше рекомендаций в нашем руководстве по структурированию проектов dbt.

Могу ли я добавлять тесты и описания в блок конфигурации?

dbt позволяет определять конфигурации узлов в файлах .yml, в дополнение к блокам config() и dbt_project.yml. Но обратное не всегда верно: есть вещи в файлах .yml, которые могут быть определены только там.

Некоторые свойства особенные, потому что:

• У них уникальный контекст рендеринга Jinja
• Они создают новые ресурсы проекта
• Они не имеют смысла как иерархическая конфигурация
• Это более старые свойства, которые еще не были переопределены как конфигурации

Эти свойства:

• description
• tests
• docs
• columns
• quote
• source свойства (например, loaded_at_field, freshness)
• exposure свойства (например, type, maturity)
• macro свойства (например, arguments)

Почему файлы yml для моделей и источников всегда начинаются с `version: 2`?

Когда-то структура этих файлов .yml была совсем другой (привет всем, кто использовал dbt в те времена!). Добавление version: 2 позволило нам сделать эту структуру более расширяемой.

Файлы yml ресурсов в настоящее время не требуют этой настройки. Мы поддерживаем только version: 2, если она указана. Хотя мы не планируем обновлять файлы yml до version: 3 в ближайшее время, наличие этой настройки облегчит нам введение новых структур в будущем.

Могу ли я использовать расширение файла YAML?

Нет. В настоящее время dbt будет искать только файлы с расширением .yml. В будущих версиях dbt также будет искать файлы с расширением .yaml.

Устранение распространенных ошибок

Неверная конфигурация теста, заданная в [имя модели]

Эта ошибка возникает, когда ваш .yml файл не соответствует структуре, ожидаемой dbt. Полное сообщение об ошибке может выглядеть так:

* Неверная конфигурация теста, заданная в models/schema.yml рядом с {'namee': 'event', ...}
  Неверные аргументы переданы экземпляру "UnparsedNodeUpdate": 'name' является обязательным свойством, дополнительные свойства не допускаются ('namee' было неожиданным)

Хотя это сообщение может быть многословным, оно должно помочь вам найти проблему. Здесь поле name было случайно указано как namee. Чтобы исправить эту ошибку, убедитесь, что ваш .yml соответствует ожидаемой структуре, описанной в этом руководстве.

Неверный синтаксис в вашем файле schema.yml

Если ваш .yml файл не является допустимым yaml, dbt покажет вам ошибку, подобную этой:

Runtime Error
  Синтаксическая ошибка рядом с линией 6
  ------------------------------
  5  |   - name: events
  6  |     description; "Таблица, содержащая события кликстрима с маркетингового веб-сайта"
  7  |

  Raw Error:
  ------------------------------
  при сканировании простого ключа
    в "<unicode string>", строка 6, столбец 5:
          description; "Таблица, содержащая события кликстрима с маркетингового веб-сайта"
          ^

Эта ошибка произошла, потому что вместо двоеточия (:) после поля description случайно был использован точка с запятой (;). Чтобы решить такие проблемы, найдите .yml файл, упомянутый в сообщении об ошибке, и исправьте любые синтаксические ошибки, присутствующие в файле. Существуют онлайн-валидаторы YAML, которые могут быть полезны здесь, но будьте осторожны при отправке конфиденциальной информации сторонним приложениям!