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

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

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

(Версии dbt: v1.9 и новее)

1. Используя свойство config в файле .yml для поддерживаемых директорий ресурсов, таких как models/, snapshots/, seeds/, analyses, tests/ и других.
2. Через файл dbt_project.yml, в соответствующем ключе ресурса (models:, snapshots:, data_tests: и так далее).

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

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

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

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

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

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

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

• tags суммируются. Если для модели настроены теги в dbt_project.yml, а в её файле .sql заданы дополнительные теги, итоговый набор будет включать их все.

• При использовании конфигурации freshness более конкретная пара «ключ — значение» заменяет менее конкретное значение с тем же ключом.

• pre-hook и post-hook также суммируются.

• Словари meta объединяются поверхностно: dbt объединяет только ключи верхнего уровня и не заглядывает во вложенные словари. Если один и тот же ключ верхнего уровня встречается на нескольких уровнях, более конкретное значение полностью заменяет менее конкретное — даже если это значение само является словарём. Ключи верхнего уровня, встречающиеся только на одном уровне, сохраняются. Например, если в dbt_project.yml задано:

  +meta: {owner: "alice", dagster: {automation_condition: "eager"}}

  Сообщить об ошибке в коде

  а в модели задано:

  meta: {dagster: {asset_key: "my_key"}}

  Сообщить об ошибке в коде

  результат будет следующим:

  {owner: "alice", dagster: {asset_key: "my_key"}}

  Сообщить об ошибке в коде

  owner сохраняется, поскольку встречается только на одном уровне. dagster встречается на обоих уровнях, поэтому более конкретное значение заменяет его целиком — а поскольку при объединении содержимое dagster не рассматривается, вложенный ключ automation_condition теряется. При глубоком (рекурсивном) объединении вложенные ключи, напротив, объединились бы, дав результат dagster: {automation_condition: "eager", asset_key: "my_key"}. В meta этого не происходит — вложенные словари заменяются, а не объединяются.

Какая конфигурация имеет приоритет на разных уровнях

Для перезаписи и объединения конфигураций, наследуемых с нескольких уровней, действуют следующие общие правила:

• Конфигурации на уровне узла (более конкретные) перезаписывают конфигурации на уровне проекта (менее конкретные).
• Для источников конфигурации на уровне таблицы (более конкретные) перезаписывают конфигурации на уровне источника (менее конкретные).
• Конфигурация корневого проекта в dbt_project.yml перезаписывает конфигурацию в файлах пакетов. Это позволяет пользователям управлять поведением пакетов, устанавливаемых с помощью dbt deps, без необходимости напрямую редактировать код в файлах этих пакетов.

Префикс +

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

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

Дополнительную информацию см. в разделе Использование префикса +.

Пример

Ниже приведён пример, в котором для проекта определены и 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:
              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']
              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 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.

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

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

Эта ошибка возникает, когда ваш файл .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 файл соответствует ожидаемой структуре, описанной в этом руководстве.

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

Если ваш файл .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