# contract

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

* `name` и `data_type` для каждого столбца
* Дополнительные [ограничения (`constraints`)](https://docs.getdbt.tech/reference/resource-properties/constraints.md), поддерживаемые данной материализацией и платформой данных

Это даёт всем, кто обращается к модели в dbt или за его пределами, предсказуемый набор столбцов.

Контракты позволяют управлять проверкой соблюдения схем — как для отдельной модели, так и единообразно для множества моделей в проекте.

## Предварительные требования

**Контракты моделей поддерживаются в следующих файлах и моделях, а также на следующих платформах:**

* Файл `dbt_project.yml`

* Файл `properties.yml`

* SQL-модели

* Модели с одной из следующих материализаций:

  * `table`
  * `view` — представления поддерживают имена столбцов и типы данных, но не `constraints`
  * `incremental` — с `on_schema_change: append_new_columns` или `on_schema_change: fail`

* Некоторые платформы данных, однако поддерживаемые и [принудительно применяемые `constraints`](https://docs.getdbt.tech/reference/resource-properties/constraints.md) различаются в зависимости от платформы

**Контракты моделей *НЕ* поддерживаются в следующих случаях:**

* Python-модели
* SQL-модели с материализацией `materialized view` или `ephemeral`
* Пользовательские материализации (если их автор не добавил поддержку)
* Модели с рекурсивными CTE в BigQuery
* Другие типы ресурсов, такие как `sources`, `seeds`, `snapshots` и так далее

Обратитесь к разделу [Примеры](https://docs.getdbt.tech/reference/resource-configs/contract.md#examples), чтобы узнать, как применять контракты в вашем проекте.

## Алиасинг типов данных

dbt использует встроенный алиасинг типов для `data_type`, определенного в вашем YAML. Например, вы можете указать `string` в вашем контракте, и на Postgres/Redshift dbt преобразует его в `text`. Если dbt не распознает имя `data_type` среди известных алиасов, он передаст его как есть. Это включено по умолчанию, но вы можете отказаться, установив `alias_types` в `false`.

Пример отключения:

FOLDER\_NAME/FILE\_NAME.yml

```yml

models:
  - name: my_model
    config:
      contract:
        enforced: true
        alias_types: false  # true по умолчанию
```

## Размер, точность и масштаб

Когда dbt сравнивает типы данных, он не будет сравнивать такие детальные характеристики, как размер, точность или масштаб. Мы считаем, что вам не стоит беспокоиться о разнице между `varchar(256)` и `varchar(257)`, так как это не сильно влияет на опыт пользователей, выполняющих запросы далее по цепочке. Вы можете добиться более точного утверждения, [написав или используя пользовательский тест](https://docs.getdbt.tech/best-practices/writing-custom-generic-tests.md).

Обратите внимание: необходимо указать размер varchar или масштаб числового типа, иначе dbt использует значения по умолчанию. Например, если тип `numeric` по умолчанию имеет точность 38 и масштаб 0, то числовой столбец хранит 0 цифр после десятичного разделителя (то есть только целые числа), что может привести к ошибке при проверке соблюдения контракта. Чтобы избежать такого неявного приведения типов, укажите в `data_type` ненулевой масштаб, например `numeric(38, 6)`. dbt версии 1.7 и выше выводит предупреждение, если при указании числового типа данных вы не задаёте точность и масштаб.

### Примеры

models/dim\_customers.yml

```yml
models:
  - name: dim_customers
    config:
      materialized: table
      contract:
        enforced: true
    columns:
      - name: customer_id
        data_type: int
        constraints:
          - type: not_null
      - name: customer_name
        data_type: string
      - name: non_integer
        data_type: numeric(38,3)
```

Предположим, ваша модель определена как:

models/dim\_customers.sql

```sql
select
  'abc123' as customer_id,
  'My Best Customer' as customer_name
```

Когда вы выполняете `dbt run` для вашей модели, *до* того, как dbt материализует ее как таблицу в базе данных, вы увидите эту ошибку:

```txt
20:53:45  Ошибка компиляции в модели dim_customers (models/dim_customers.sql)
20:53:45    Эта модель имеет применяемый контракт, который не выполнен.
20:53:45    Пожалуйста, убедитесь, что имя, data_type и количество столбцов в вашем контракте соответствуют столбцам в определении вашей модели.
20:53:45
20:53:45    | column_name | definition_type | contract_type | mismatch_reason    |
20:53:45    | ----------- | --------------- | ------------- | ------------------ |
20:53:45    | customer_id | TEXT            | INT           | несоответствие типа данных |
20:53:45
20:53:45
20:53:45    > в макросе assert_columns_equivalent (macros/materializations/models/table/columns_spec_ddl.sql)
```

### Project YAML

Включите проверку соблюдения контрактов в `dbt_project.yml`, чтобы единообразно применять контракты к нескольким моделям:

```yml

models:
  property_management:  # замените на имя вашего проекта dbt
    +contract:
      enforced: true
```

### Properties YAML

Определите контракт модели в `properties.yml`, указав ожидаемые столбцы и типы данных:

```yml

models:
  - name: stg_rental_applications  # замените на имя вашей модели
    config:
      contract:
        enforced: true
    columns:
      - name: column_1_id  # пример столбца с идентификатором. Замените на ваш столбец
        data_type: int    # замените на тип данных вашего столбца
      - name: column_2_created_at  # пример столбца, содержащего время создания
        data_type: timestamp
      - name: column_3_status      # пример столбца статуса, в котором обычно хранятся текстовые значения ("active", "pending", "completed" и т. д.)
        data_type: string
```

### Конфигурация в SQL-файле

Включите проверку соблюдения контракта в SQL-файле модели, если хотите применить его к отдельной модели и сохранить возможность точной настройки:

```sql

{{ config(
  contract = { "enforced": true }  -- Включает проверку соблюдения контракта для этой модели
) }}

select
  column_1_id,          -- замените на ваш столбец
  column_2_created_at,  -- замените на ваш столбец
  column_3_status       -- замените на ваш столбец
from {{ source('property_management', 'rental_applications') }}  -- замените на имя вашего источника и таблицы
```

Подробнее о поддерживаемых параметрах конфигурации для SQL-файлов моделей, `dbt_project.yml` и `properties.yml` см. в разделе [Общие настройки](https://docs.getdbt.tech/reference/model-configs.md#general-configurations).

### Инкрементальные модели и `on_schema_change`

Почему для инкрементальных моделей требуется также указывать [`on_schema_change`](https://docs.getdbt.tech/docs/build/incremental-models.md#what-if-the-columns-of-my-incremental-model-change), и почему именно `append_new_columns` или `fail`?

Представьте:

* Вы добавляете новый столбец и в SQL, и в спецификацию YAML
* Вы не задаёте `on_schema_change` или задаёте `on_schema_change: 'ignore'`
* dbt фактически не добавляет этот новый столбец в существующую таблицу — и операция upsert/merge по-прежнему выполняется успешно, поскольку она использует только уже существующие столбцы целевой таблицы (это давно установленное поведение)
* В результате возникает расхождение между контрактом, определённым в YAML, и фактической таблицей в базе данных — а значит, контракт теперь некорректен!

Почему `append_new_columns` (или `fail`), а не `sync_all_columns`? Потому что удаление существующих столбцов — это несовместимое изменение для моделей с контрактом! `sync_all_columns` работает как `append_new_columns`, но также удаляет столбцы, которые были удалены из модели, а для моделей с контрактом этого делать нельзя без перехода на новую версию.

## Устранение неполадок

 Я получаю ошибку несоответствия контракту

**Что пошло не так:** Если для модели включена проверка контракта, dbt проверяет, что набор данных, возвращаемый моделью, в точности соответствует значениям `name` и `data_type`, определённым в YAML для каждого столбца; при несоответствии dbt выдаёт ошибку.

**Решение:** Убедитесь, что `name`, `data_type` и количество столбцов в контракте соответствуют столбцам в определении модели. Подробнее см. в [документации по контрактам](https://docs.getdbt.tech/reference/resource-configs/contract.md).

 Новый столбец не появляется в моей инкрементальной модели

**Что пошло не так:** Контракты для инкрементальных моделей поддерживаются, когда для `on_schema_change` задано значение `append_new_columns` или `fail`. Если вы добавляете новый столбец, но не задаёте `on_schema_change` (или задаёте значение `ignore`), dbt не добавляет этот столбец в существующую таблицу, что может привести к расхождению между контрактом, определённым в YAML, и фактической схемой таблицы.

**Решение:** Задайте `on_schema_change: append_new_columns` (или `fail`) для инкрементальных моделей с контрактом. Подробнее см. в разделе [Инкрементальные модели и `on_schema_change`](https://docs.getdbt.tech/docs/mesh/govern/model-contracts.md).

 Из таблицы моей инкрементальной модели исчез столбец

**Что пошло не так:** `sync_all_columns` добавляет все новые столбцы в существующую таблицу и удаляет все столбцы, которые теперь отсутствуют, поэтому столбец может быть удалён из целевой таблицы, если его нет в новом запросе модели.

**Решение:** Для инкрементальных моделей с контрактом используйте `append_new_columns` (или `fail`), а не `sync_all_columns`. Удаление существующих столбцов — это несовместимое изменение для моделей с контрактом. Подробнее см. в разделе [Инкрементальные модели и `on_schema_change`](https://docs.getdbt.tech/docs/mesh/govern/model-contracts.md).

 Я получаю неожиданную ошибку несоответствия типов данных

**Что пошло не так:** dbt применяет встроенное сопоставление псевдонимов типов к значениям `data_type` в YAML, а использование точности и масштаба по умолчанию (особенно для `numeric`) может привести к неявному преобразованию типов, из-за которого проверка контракта может завершиться ошибкой.

**Решение:** Чтобы отключить сопоставление псевдонимов типов, задайте `alias_types: false`. Чтобы избежать неявного преобразования числовых типов, укажите `data_type` с ненулевым масштабом (например, `numeric(38, 6)`). Подробнее см. в [документации по контрактам](https://docs.getdbt.tech/reference/resource-configs/contract.md).

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

* [Что такое контракт модели?](https://docs.getdbt.tech/docs/mesh/govern/model-contracts.md)
* [Определение `columns`](https://docs.getdbt.tech/reference/resource-properties/columns.md)
* [Определение `constraints`](https://docs.getdbt.tech/reference/resource-properties/constraints.md)
