# Определение свойств

Узнайте, как определять свойства для ваших ресурсов в файле properties.yml

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

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

к сведению

#### Файлы schema.yml

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

Теперь мы называем эти файлы `properties.yml`. (Разумеется, вы по‑прежнему можете называть свои файлы `schema.yml`.)

### Какие properties *не* являются также configs?

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

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

* для них используется уникальный контекст рендеринга Jinja;
* они создают новые ресурсы проекта;
* они не имеют смысла как иерархическая конфигурация;
* это более старые свойства, которые ещё не были переопределены как configs.

К таким свойствам относятся:

* [`columns`](https://docs.getdbt.tech/reference/resource-properties/columns.md)
* [`deprecation_date`](https://docs.getdbt.tech/reference/resource-properties/deprecation_date.md)
* [`description`](https://docs.getdbt.tech/reference/resource-properties/description.md)
* [`quote`](https://docs.getdbt.tech/reference/resource-properties/columns.md#quote)
* [`source` properties](https://docs.getdbt.tech/reference/source-properties.md) (например, `loaded_at_field`)
* [`exposure` properties](https://docs.getdbt.tech/reference/exposure-properties.md) (например, `type`, `maturity`)
  * Обратите внимание: хотя большинство свойств exposure необходимо задавать напрямую в файлах `properties.yml`, вы можете установить конфигурацию [`enabled`](https://docs.getdbt.tech/reference/resource-configs/enabled.md) на [уровне проекта](https://docs.getdbt.tech/reference/exposure-properties.md#project-level-configs) в файле `dbt_project.yml`.
* [`macro` properties](https://docs.getdbt.tech/reference/macro-properties.md) (например, `arguments`)
* [`tests`](https://docs.getdbt.tech/reference/resource-properties/data-tests.md)
* [`versions`](https://docs.getdbt.tech/reference/resource-properties/versions.md)

## Пример

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

models/jaffle\_shop.yml

```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](https://docs.getdbt.tech/reference/model-properties.md) и [configs](https://docs.getdbt.tech/reference/model-configs.md)
* Источники: [properties](https://docs.getdbt.tech/reference/source-properties.md) и [configs](https://docs.getdbt.tech/reference/source-configs.md)
* Seed-данные: [properties](https://docs.getdbt.tech/reference/seed-properties.md) и [configs](https://docs.getdbt.tech/reference/seed-configs.md)
* Снимки (snapshots): [properties](https://docs.getdbt.tech/reference/snapshot-properties.md)
* Анализы: [properties](https://docs.getdbt.tech/reference/analysis-properties.md)
* Макросы: [properties](https://docs.getdbt.tech/reference/macro-properties.md)
* Экспозиции (exposures): [properties](https://docs.getdbt.tech/reference/exposure-properties.md)

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

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

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

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

Посмотрите [документацию](https://docs.getdbt.tech/reference/configs-and-properties.md) для получения дополнительной информации.

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

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

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

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

Выберите то, что подходит вашей команде. У нас есть больше рекомендаций в нашем руководстве по [структурированию проектов dbt](https://docs.getdbt.tech/best-practices/how-we-structure/1-guide-overview.md).

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

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

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

Выберите то, что подходит вашей команде. У нас есть больше рекомендаций в нашем руководстве по [структурированию проектов dbt](https://docs.getdbt.tech/best-practices/how-we-structure/1-guide-overview.md).

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

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

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

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

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

* [`description`](https://docs.getdbt.tech/reference/resource-properties/description.md)
* [`tests`](https://docs.getdbt.tech/reference/resource-properties/data-tests.md)
* [`docs`](https://docs.getdbt.tech/reference/resource-configs/docs.md)
* `columns`
* [`quote`](https://docs.getdbt.tech/reference/resource-properties/columns.md#quote)
* свойства [`source`](https://docs.getdbt.tech/reference/source-properties.md) (например, `loaded_at_field`, `freshness`)
* свойства [`exposure`](https://docs.getdbt.tech/reference/exposure-properties.md) (например, `type`, `maturity`)
* свойства [`macro`](https://docs.getdbt.tech/reference/resource-properties/arguments.md) (например, `arguments`)

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

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

Начиная с [dbt v1.5](<https://docs.getdbt.tech/docs/dbt-versions/dbt-upgrade/Older versions/upgrading-to-v1.5/.md#quick-hits>), ключ `version:` верхнего уровня необязателен во всех YAML-файлах ресурсов. Если он указан, поддерживается только значение `version: 2`.

Также, начиная с версии 1.5, и [`config-version: 2`](https://docs.getdbt.tech/reference/project-configs/config-version.md), и ключ верхнего уровня `version:` в файле `dbt_project.yml` являются необязательными.

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

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

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

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

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

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

```text
* 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 покажет ошибку вида:

```text
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, однако будьте осторожны и не отправляйте конфиденциальную информацию в сторонние сервисы!
