Перейти к основному содержимому

contract

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

  • name и data_type для каждого столбца
  • Дополнительные ограничения (constraints), поддерживаемые данной материализацией и платформой данных

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

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

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

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

  • Файл dbt_project.yml
  • Файл properties.yml
  • SQL-модели
  • Модели с одной из следующих материализаций:
    • table
    • view — представления поддерживают имена столбцов и типы данных, но не constraints
    • incremental — с 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.

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

FOLDER_NAME/FILE_NAME.yml

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/dim_customers.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
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)

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


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

Подробнее о поддерживаемых параметрах конфигурации для 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, но также удаляет столбцы, которые были удалены из модели, а для моделей с контрактом этого делать нельзя без перехода на новую версию.

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

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

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

Решение: Убедитесь, что name, data_type и количество столбцов в контракте соответствуют столбцам в определении модели. Подробнее см. в документации по контрактам.

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

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

Решение: Задайте on_schema_change: append_new_columns (или fail) для инкрементальных моделей с контрактом. Подробнее см. в разделе Инкрементальные модели и on_schema_change.

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

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

Решение: Для инкрементальных моделей с контрактом используйте append_new_columns (или fail), а не sync_all_columns. Удаление существующих столбцов — это несовместимое изменение для моделей с контрактом. Подробнее см. в разделе Инкрементальные модели и on_schema_change.

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

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

Решение: Чтобы отключить сопоставление псевдонимов типов, задайте alias_types: false. Чтобы избежать неявного преобразования числовых типов, укажите data_type с ненулевым масштабом (например, numeric(38, 6)). Подробнее см. в документации по контрактам.

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

0
Loading