contract
Когда конфигурация contract применяется в обязательном порядке, dbt гарантирует, что набор данных, возвращаемый вашей моделью, в точности соответствует атрибутам, определённым в YAML:
nameиdata_typeдля каждого столбца- Дополнительные ограничения (
constraints), поддерживаемые данной материализацией и платформой данных
Это даёт всем, кто обращается к модели в dbt или за его пределами, предсказуемый набор столбцов.
Контракты позволяют управлять проверкой соблюдения схем — как для отдельной модели, так и единообразно для множества моделей в проекте.
Предварительные требования
Контракты моделей поддерживаются в следующих файлах и моделях, а также на следующих платформах:
- Файл
dbt_project.yml - Файл
properties.yml - SQL-модели
- Модели с одной из следующих материализаций:
tableview— представления поддерживают имена столбцов и типы данных, но неconstraintsincremental— сon_schema_change: append_new_columnsилиon_schema_change: fail
- Некоторые платформы данных, однако поддерживаемые и принудительно применяемые
constraintsразличаются в зависимости от платформы
Контракты моделей НЕ поддерживаются в следующих случаях:
- Python-модели
- SQL-модели с материализацией
materialized viewилиephemeral - Пользовательские материализации (если их автор не добавил поддержку)
- Модели с рекурсивными CTE в BigQuery
- Другие типы ресурсов, такие как
sources,seeds,snapshotsи так далее
Обратитесь к разделу Примеры, чтобы узнать, как применять контракты в вашем проекте.
Алиасинг типов данных
dbt использует встроенный алиасинг типов для data_type, определенного в вашем YAML. Например, вы можете указать string в вашем контракте, и на Postgres/Redshift dbt преобразует его в text. Если dbt не распознает имя data_type среди известных алиасов, он передаст его как есть. Это включено по умолчанию, но вы можете отказаться, установив alias_types в false.
Пример отключения:
models:
- name: my_model
config:
contract:
enforced: true
alias_types: false # true по умолчанию
Размер, точность и масштаб
Когда dbt сравнивает типы данных, он не будет сравнивать такие детальные характеристики, как размер, точность или масштаб. Мы считаем, что вам не стоит беспокоиться о разнице между varchar(256) и varchar(257), так как это не сильно влияет на опыт пользователей, выполняющих запросы далее по цепочке. Вы можете добиться более точного утверждения, написав или используя пользовательский тест.
Обратите внимание: необходимо указать размер varchar или масштаб числового типа, иначе dbt использует значения по умолчанию. Например, если тип numeric по умолчанию имеет точность 38 и масштаб 0, то числовой столбец хранит 0 цифр после десятичного разделителя (то есть только целые числа), что может привести к ошибке при проверке соблюдения контракта. Чтобы избежать такого неявного приведения типов, укажите в data_type ненулевой масштаб, например numeric(38, 6). dbt версии 1.7 и выше выводит предупреждение, если при указании числового типа данных вы не задаёте точность и масштаб.
Примеры
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)
Предположим, ваша модель определена как:
select
'abc123' as customer_id,
'My Best Customer' as customer_name
Когда вы выполняете dbt run для вашей модели, до того, как dbt материализует ее как таблицу в базе данных, вы увидите эту ошибку:
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
- Properties YAML
- Конфигурация в SQL-файле
Включите проверку соблюдения контрактов в dbt_project.yml, чтобы единообразно применять контракты к нескольким моделям:
models:
property_management: # замените на имя вашего проекта dbt
+contract:
enforced: true
Определите контракт модели в properties.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-файле модели, если хотите применить его к отдельной модели и сохранить возможность точной настройки:
{{ 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 см. в разделе Общие настройки.
Инкрементальные модели и on_schema_change
Почему для инкрементальных моделей требуется также указывать on_schema_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, но также удаляет столбцы, которые были удалены из модели, а для моделей с контрактом этого делать нельзя без перехода на новую версию.