Добавление тестов данных в ваш DAG
Связанная справочная документация
Тесты теперь называются data tests, чтобы избежать путаницы с unit tests. YAML-ключ tests: по‑прежнему поддерживается как алиас для data_tests:. Подробнее см. в разделе New data_tests: syntax.
Обзор
Data tests — это утверждения, которые вы задаёте для своих моделей и других ресурсов в проекте dbt (например, sources, seeds и snapshots). Когда вы запускаете dbt test, dbt сообщает, проходит ли каждый тест в вашем проекте или завершается с ошибкой.
Вы можете использовать тесты данных для улучшения целостности SQL в каждой модели, делая утверждения о сгенерированных результатах. Из коробки вы можете проверить, содержит ли указанный столбец в модели только ненулевые значения, уникальные значения или значения, которые имеют соответствующее значение в другой модели (например, customer_id для order соответствует id в модели customers), и значения из указанного списка. Вы можете расширить тесты данных, чтобы они соответствовали бизнес-логике, специфичной для вашей организации — любое утверждение, которое вы можете сделать о своей модели в форме запроса select, может быть преобразовано в тест данных.
Тесты данных возвращают набор записей, не прошедших проверку. Универсальные тесты данных (также известные как тесты схемы) определяются с помощью блоков test.
Как и почти всё в dbt, тесты данных — это SQL-запросы. В частности, это операторы select, которые выбирают записи, не прошедшие проверку, то есть опровергающие ваше утверждение. Если вы утверждаете, что значения столбца в модели уникальны, тестовый запрос выбирает дубликаты; если вы утверждаете, что столбец никогда не содержит null, тест ищет значения null. Если тест данных не возвращает ни одной строки, не прошедшей проверку, он считается пройденным, а ваше утверждение — подтверждённым.
В dbt есть два способа определения тестов данных:
- Сингулярный тест данных в простейшем виде — это SQL-запрос, который возвращает строки, не прошедшие проверку. Сохраните этот запрос в файле
.sqlв каталоге тестов. Теперь это тест данных, который будет выполняться командойdbt test. - Универсальный тест данных — это параметризованный запрос, принимающий аргументы. Запрос теста определяется в специальном блоке
test(как макрос). После определения вы можете ссылаться на универсальный тест по имени в своих файлах.yml— задавать его для моделей, столбцов, источников, снимков и seed-файлов. В dbt есть четыре встроенных универсальных теста данных, и мы рекомендуем их использовать!
Определение тестов данных — отличный способ подтвердить, что ваши выходные и входные данные соответствуют ожиданиям, и помогает предотвратить регрессии при изменении вашего кода. Поскольку вы можете использовать их снова и снова, делая аналогичные утверждения с небольшими вариациями, общие тесты данных, как правило, гораздо более распространены — они должны составлять основную часть вашего набора тестов данных dbt. Тем не менее, оба способа определения тестов данных имеют свое время и место.
Если вы только начинаете работать с dbt, мы рекомендуем ознакомиться с нашим онлайн-курсом dbt Fundamentals или кратким руководством, чтобы создать свой первый dbt‑проект с моделями и тестами.
Единичные тесты данных
Самый простой способ определить тест данных — это написать точный SQL, который вернет неудачные записи. Мы называем их "единичными" тестами данных, потому что это одноразовые утверждения, используемые для одной цели.
Эти тесты определяются в файлах .sql, обычно в каталоге tests (указанном в конфигурации test-paths). Примечание: Каталог tests/ (test-paths) предназначен только для единичных и универсальных тестов данных (SQL). YAML-определения модульных тестов должны находиться в каталогах, указанных в model-paths вашего проекта (например, в каталоге models/), а не в tests/. В определении теста можно использовать Jinja (включая ref и source), как и при создании моделей. Каждый файл .sql содержит один оператор select и определяет один тест данных:
-- Возвраты имеют отрицательную сумму, поэтому общая сумма всегда должна быть >= 0.
-- Поэтому возвращаем записи, где total_amount < 0, чтобы тест не прошел.
select
order_id,
sum(amount) as total_amount
from {{ ref('fct_payments') }}
group by 1
having total_amount < 0
Название теста совпадает с именем файла: assert_total_payment_amount_is_positive.
Примечание:
- Не ставьте точку с запятой (
;) в конце SQL‑запроса в файлах с одиночными тестами, так как это может привести к сбою выполнения data‑теста. - Одиночные data‑тесты, размещённые в директории
tests, автоматически выполняются при запускеdbt test. Не ссылайтесь на одиночные тесты вmodel_name.yml, так как они не рассматриваются как generic‑тесты или макросы, и это приведёт к ошибке.
Чтобы добавить описание к одиночному data‑тесту в вашем проекте, добавьте файл .yml в директорию tests, например tests/schema.yml, со следующим содержимым:
data_tests:
- name: assert_total_payment_amount_is_positive
description: >
Возвраты имеют отрицательную сумму, поэтому общая сумма всегда должна быть >= 0.
Поэтому возвращаем записи, где общая сумма < 0, чтобы тест не прошел.
Единичные тесты данных настолько просты, что вы можете обнаружить, что пишете одну и ту же базовую структуру снова и снова, только меняя имя столбца или модели. В этот момент тест уже не так уж и единичен! В этом случае мы рекомендуем общие тесты данных.
Универсальные тесты данных
Некоторые тесты данных являются универсальными: их можно использовать многократно. Универсальный тест данных определяется в блоке test, который содержит параметризованный запрос и принимает аргументы. Он может выглядеть так:
{% test not_null(model, column_name) %}
select *
from {{ model }}
where {{ column_name }} is null
{% endtest %}
Обратите внимание на два аргумента, model и column_name, которые затем подставляются в запрос с помощью шаблонизации. Именно это делает тест данных «универсальным»: его можно определить для любого количества столбцов в любом количестве моделей, и dbt передаст соответствующие значения model и column_name. После определения такого универсального теста его можно добавить в качестве свойства к любой существующей модели (или источнику, seed-файлу либо снимку). Эти свойства добавляются в файлы .yml в том же каталоге, где находится ваш ресурс.
Если это ваш первый опыт работы с добавлением свойств к ресурсу, ознакомьтесь с документацией по объявлению свойств.
По умолчанию в dbt уже определены четыре универсальных теста данных: unique, not_null, accepted_values и relationships. Вот полный пример использования этих тестов для модели orders:
models:
- name: orders
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', 'returned']
- name: customer_id
data_tests:
- relationships:
arguments:
to: ref('customers')
field: id
Простыми словами, эти тесты данных означают следующее:
unique: значения в столбцеorder_idмоделиordersдолжны быть уникальнымиnot_null: столбецorder_idмоделиordersне должен содержать значения nullaccepted_values: значения в столбцеstatusмоделиordersдолжны быть одним из следующих:'placed','shipped','completed'или'returned'relationships: каждое значениеcustomer_idв моделиordersдолжно существовать как значениеidв таблицеcustomersтаблица (это также называется ссылочной целостностью)
За кулисами dbt формирует запрос select для каждого теста данных, используя параметризованный запрос из блока универсального теста. Эти запросы возвращают строки, для которых ваше утверждение не выполняется; если тест возвращает ноль строк, проверка вашего утверждения пройдена.
Вы можете найти больше информации об этих тестах данных, а также о дополнительных настройках (включая severity и tags) в разделе справки. Также вы можете добавлять описания в Jinja‑макрос, который реализует основную логику обобщённого теста данных. Подробнее см. в разделе Add description to generic data test logic.
Больше общих тестов данных
Этих четырёх тестов достаточно, чтобы начать работу. Очень скоро вы обнаружите, что хотите использовать более широкий набор тестов данных — и это хорошо! Вы также можете установить обобщённые (generic) тесты данных из пакета или написать свои собственные, чтобы использовать их (и переиспользовать) в рамках проекта dbt. Подробнее об этом читайте в руководстве по созданию собственных generic‑тестов данных.
В некоторых open‑source пакетах уже определены generic‑тесты данных, например в dbt-utils и dbt-expectations — перейдите к документации по пакетам, чтобы узнать больше!
Пример
Чтобы добавить generic (или «schema») тест данных в ваш проект:
- Добавьте файл
.ymlв директориюmodels, напримерmodels/schema.yml, со следующим содержимым (возможно, вам потребуется скорректировать значенияname:для уже существующей модели).
models:
- name: orders
columns:
- name: order_id
data_tests:
- unique
- not_null
- Запустите
команду dbt test:
$ dbt test
Found 3 models, 2 tests, 0 snapshots, 0 analyses, 130 macros, 0 operations, 0 seed files, 0 sources
17:31:05 | Concurrency: 1 threads (target='learn')
17:31:05 |
17:31:05 | 1 of 2 START test not_null_order_order_id..................... [RUN]
17:31:06 | 1 of 2 PASS not_null_order_order_id........................... [PASS in 0.99s]
17:31:06 | 2 of 2 START test unique_order_order_id....................... [RUN]
17:31:07 | 2 of 2 PASS unique_order_order_id............................. [PASS in 0.79s]
17:31:07 |
17:31:07 | Finished running 2 tests in 7.17s.
Completed successfully
Done. PASS=2 WARN=0 ERROR=0 SKIP=0 TOTAL=2
- Посмотрите SQL, который выполняет dbt, одним из следующих способов:
- dbt: откройте вкладку Details.
- dbt v1: просмотрите каталог
target/compiled
Тест на уникальность
- Скомпилированный SQL
- Шаблонизированный SQL
select *
from (
select
order_id
from analytics.orders
where order_id is not null
group by order_id
having count(*) > 1
) validation_errors
select *
from (
select
{{ column_name }}
from {{ model }}
where {{ column_name }} is not null
group by {{ column_name }}
having count(*) > 1
) validation_errors
Тест на отсутствие null
- Скомпилированный SQL
- Шаблонизированный SQL
select *
from analytics.orders
where order_id is null
select *
from {{ model }}
where {{ column_name }} is null
Запуск только тестов данных
Чтобы запускать тесты данных, исключая модульные тесты, используйте селектор test_type — он работает во всех движках (dbt v1 и dbt v2):
dbt test --select "test_type:data"
В dbt (v1.9+) также можно использовать dbt test --resource-type test. Дополнительные варианты приведены в разделе Примеры выбора тестов.
Группировка тестов данных
В dbt v2 можно сократить количество запросов, которые dbt выполняет для тестов, включив пакетное выполнение тестов. При пакетном выполнении тесты unique и not_null, привязанные к одной модели, объединяются в один запрос для каждого типа теста, при этом каждый тест по-прежнему сообщает собственный результат: пройден или не пройден.
Сохранение результатов тестов данных с нарушениями
Обычно запрос теста данных определяет нарушения в процессе выполнения. Если задать необязательный флаг --store-failures или параметры конфигурации store_failures либо store_failures_as, dbt сначала сохранит результаты тестового запроса в таблицу в базе данных, а затем выполнит запрос к этой таблице, чтобы подсчитать количество нарушений.
Этот рабочий процесс позволяет вам быстрее запрашивать и изучать неудачные записи в процессе разработки:
Обратите внимание: если вы решите сохранять записи, не прошедшие тесты данных:
- По умолчанию таблицы с результатами тестов создаются в схеме с суффиксом или именем
dbt_test__audit. Это значение можно изменить с помощью настройкиschema. (Подробнее об именовании схем см. в разделе использование пользовательских схем.) - Результаты теста всегда будут заменять предыдущие записи, не прошедшие тот же тест.
Новый синтаксис data_tests:
Исторически тесты данных в dbt назывались просто «тестами», поскольку были единственным доступным видом тестирования. С появлением модульных тестов ключ tests: был переименован в data_tests:.
dbt по-прежнему поддерживает tests: в файлах конфигурации YAML для обратной совместимости, и вы можете встретить его в нашей документации. Однако нельзя одновременно использовать ключи tests и data_tests для одного и того же ресурса (например, одной модели).
models:
- name: orders
columns:
- name: order_id
data_tests:
- unique
- not_null
data_tests:
+store_failures: true
Тесты с arguments и без него
Для некоторых универсальных тестов данных достаточно указать только имя теста. Другим нужны дополнительные входные параметры, которые следует вкладывать в свойство arguments (доступно в версии v1.10.5 и выше). В v2 вложение входных параметров теста в arguments обязательно. Если указать входные параметры теста как свойства верхнего уровня рядом с именем теста, возникнет ошибка валидации.
Без arguments
Тестам unique и not_null не нужны дополнительные входные параметры. Например, unique проверяет, что в столбце нет повторяющихся значений, а not_null — что в столбце нет значений null. dbt уже определяет модель и столбец из контекста YAML, поэтому достаточно указать имя теста:
models:
- name: orders
columns:
- name: order_id
data_tests:
- unique
- not_null
С arguments
Тестам accepted_values и relationships нужны дополнительные входные параметры для макроса теста. Например, accepted_values проверяет, что значения столбца входят в заданный список, а relationships — что каждое значение существует в другой модели (ссылочная целостность). Вложите эти параметры в arguments::
models:
- name: orders
columns:
- name: status
data_tests:
- accepted_values:
arguments: # доступно в версии v1.10.5 и выше.
values: ['placed', 'shipped', 'completed', 'returned']
- name: customer_id
data_tests:
- relationships:
arguments:
to: ref('customers')
field: id
Используйте arguments: для входных параметров макроса теста (например, values, to и field). Используйте config для параметров фреймворка, таких как severity, where и store_failures.
Если раньше вы указывали входные параметры теста как свойства верхнего уровня рядом с именем теста, перенесите их в arguments:. Подробнее см. require_generic_test_arguments_property и MissingArgumentsPropertyInGenericTestDeprecation.
Добавление контекста к строкам, не прошедшим проверку
Тесты данных возвращают по одной строке для каждого нарушения. Столбцы, указанные в SQL-запросе select вашего теста, — это те столбцы, которые вы видите при разборе нарушений, в том числе при сохранении результатов тестов с нарушениями.
Встроенные тесты часто возвращают только значение, не прошедшее проверку. Чтобы добавить контекст к каждой такой строке, напишите единичный тест данных (или собственный универсальный тест данных), который выбирает нужные дополнительные столбцы. Ниже приведён единичный тест на основе теста accepted_values из примера выше, который также включает customer_id для дополнительного контекста.
select
order_id,
status,
customer_id
from {{ ref('orders') }}
where status not in ('placed', 'shipped', 'completed', 'returned')
При выполнении dbt test --store-failures (или настройке параметра store_failures) dbt сохраняет эти строки, чтобы вы могли запрашивать их и проверять каждый выбранный столбец.
