Определение конфигураций

Узнайте, как определять конфигурации для ваших ресурсов в dbt‑проекте

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

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

Наиболее специфичная конфигурация всегда имеет приоритет. В общем случае это следует порядку, указанному выше: блок config() внутри файла → свойства, определённые в .yml файле → конфигурация, заданная в проектном файле.

Примечание: обобщённые data tests работают немного иначе с точки зрения специфичности. Подробнее см. test configs.

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

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

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

Большинство конфигураций при иерархическом применении «перезаписываются» (clobbered). Если доступно более специфичное значение, оно полностью заменяет менее специфичное. Однако некоторые конфигурации имеют иное поведение при объединении:

• tags являются аддитивными. Если для модели заданы теги в dbt_project.yml, а дополнительные теги указаны в её .sql файле, итоговый набор тегов будет включать их все.
• Словари meta объединяются (более специфичная пара ключ‑значение заменяет менее специфичное значение с тем же ключом).
• При использовании конфигурации freshness более специфичная пара ключ‑значение заменяет менее специфичное значение с тем же ключом.
• pre-hook и post-hook также являются аддитивными.
• Для перезаписываемых и объединяемых конфигураций, наследуемых с нескольких уровней, действуют общие правила:
  • Конфигурации на уровне ноды (более специфичные) перезаписывают конфигурации на уровне проекта (менее специфичные).
  • Для sources конфигурации на уровне таблицы (более специфичные) перезаписывают конфигурации на уровне source (менее специфичные).
  • Конфигурация корневого проекта в dbt_project.yml перезаписывает конфигурации в файлах пакетов. Это сделано для того, чтобы пользователи могли управлять поведением пакетов, устанавливаемых через dbt deps, без необходимости напрямую редактировать код этих пакетов.

Префикс +

dbt различает имя папки и конфигурацию, используя префикс + перед именем конфигурации. Префикс + используется только для конфигураций и применяется в файле dbt_project.yml в рамках соответствующего ключа ресурса. Он не применяется к:

• Jinja-макросу config() внутри файла ресурса
• свойству config в файле .yml

Подробнее см. в разделе Using the + prefix.

Пример

Ниже приведён пример, в котором для проекта определены и sources, и models:

models/jaffle_shop.yml

version: 2

sources:
  - name: raw_jaffle_shop
    description: A replica of the postgres database used to power the jaffle_shop app.
    tables:
      - name: customers
        columns:
          - name: id
            description: Primary key of the table
            data_tests:
              - unique
              - not_null

      - name: orders
        columns:
          - name: id
            description: Primary key of the table
            data_tests:
              - unique
              - not_null

          - name: user_id
            description: Foreign key to customers

          - name: status
            data_tests:
              - accepted_values:
                  arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                    values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']


models:
  - name: stg_jaffle_shop__customers #  Must match the filename of a model -- including case sensitivity.
    config:
      tags: ['pii']
    columns:
      - name: customer_id
        data_tests:
          - unique
          - not_null

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

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

Полный список всех поддерживаемых свойств и конфигураций, разбитый по типам ресурсов, можно найти здесь:

• Модели: properties и configs
• Источники: properties и configs
• Seed-данные: properties и configs
• Снимки (snapshots): properties
• Анализы: properties
• Макросы: properties
• Экспозиции (exposures): properties

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

Нужно ли называть мой файл `.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.

Можно ли добавлять тесты и описания в SQL config-блоке?

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

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

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

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

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

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

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

Начиная с dbt Core v1.5, ключ верхнего уровня version: является необязательным во всех ресурсных YAML‑файлах. Если он указан, поддерживается только version: 2.

Также, начиная с версии 1.5, и config-version: 2, и ключ верхнего уровня version: в файле dbt_project.yml являются необязательными.

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

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

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

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

 Invalid test config given in [model name]

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

* Invalid test config given in models/schema.yml near {'namee': 'event', ...}
  Invalid arguments passed to "UnparsedNodeUpdate" instance: 'name' is a required property, Additional properties are not allowed ('namee' was unexpected)

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

 Invalid syntax in your schema.yml file

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

Runtime Error
  Syntax error near line 6
  ------------------------------
  5  |   - name: events
  6  |     description; "A table containing clickstream events from the marketing website"
  7  |

  Raw Error:
  ------------------------------
  while scanning a simple key
    in "<unicode string>", line 6, column 5:
          description; "A table containing clickstream events from the marketing website"
          ^

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

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

Создать GitHub Issue