Custom singular tests in dbt

Introduction

Custom singular tests help you check specific rules or conditions in your data. They make sure your data is correct and clean.

You want to check if a column always has unique values.

You need to confirm that a column never has null values.

You want to verify that a value in a column matches a specific condition, like being greater than zero.

You want to create a test that is not covered by built-in dbt tests.

You want to enforce business rules on your data quality.

Syntax

dbt

version: 2

models:
  - name: your_model_name
    tests:
      - your_custom_test_name:
          arg1: value1
          arg2: value2

# In tests/your_custom_test_name.sql
SELECT * FROM {{ model }}
WHERE NOT (your_condition_here)

Custom singular tests are SQL queries that return zero rows if the test passes.

Place your test SQL files inside the tests/ folder in your dbt project.

Examples

This runs a built-in unique test on the customer_id column.

dbt

version: 2

models:
  - name: customers
    tests:
      - unique_customer_id

This custom singular test checks that customer_id has no nulls.

dbt

# tests/not_null_customer_id.sql
SELECT * FROM {{ model }}
WHERE customer_id IS NULL

This runs a custom test positive_order_amount with an argument column_name.

dbt

version: 2

models:
  - name: orders
    tests:
      - positive_order_amount:
          column_name: order_amount

This test fails if any order amount is zero or negative.

dbt

# tests/positive_order_amount.sql
SELECT * FROM {{ model }}
WHERE {{ column_name }} <= 0

Sample Program

This example shows a custom singular test not_null_customer_id that checks for nulls in customer_id. The test query returns rows where customer_id is null, so the test fails if any such rows exist.

dbt

# dbt_project.yml
name: 'my_project'
version: '1.0'

# models/customers.yml
version: 2
models:
  - name: customers
    tests:
      - not_null_customer_id

# tests/not_null_customer_id.sql
SELECT * FROM {{ model }}
WHERE customer_id IS NULL

# Sample data in customers model:
# customer_id | name
# 1           | Alice
# 2           | Bob
# NULL        | Eve

# Running dbt test will run the custom test and find the NULL customer_id.

Important Notes

Custom singular tests must return zero rows to pass.

You can pass arguments to your tests via the YAML file.

Use Jinja templating to make your tests dynamic and reusable.

Summary

Custom singular tests are SQL queries that check specific data conditions.

They return zero rows if data passes the test, otherwise they fail.

You define them in tests/ and call them in your model YAML files.

Practice

1. What is the main purpose of a custom singular test in dbt?

easy

A. To automatically generate documentation for your models

B. To write your own SQL query that checks data quality and returns rows only if there are issues

C. To schedule dbt runs at specific times

D. To create new tables from existing data

Solution

1. Step 1: Understand the role of custom singular tests

   Custom singular tests are SQL queries that check data quality by returning rows only when problems exist.

2. Step 2: Compare options with this definition

   Only To write your own SQL query that checks data quality and returns rows only if there are issues describes writing a SQL query that returns rows if there are data issues, matching the purpose of custom singular tests.

3. Final Answer:

   To write your own SQL query that checks data quality and returns rows only if there are issues -> Option B

4. Quick Check:

   Custom singular test = SQL check returning problem rows [OK]

Hint: Custom singular tests return rows only when data has problems [OK]

Common Mistakes:

• Confusing tests with documentation generation
• Thinking tests create tables
• Assuming tests schedule runs

2. Which of the following is the correct way to define a custom singular test in your schema.yml file?

easy

A. tests:
- my_custom_test.sql

B. tests:
- my_custom_test:
sql: my_custom_test.sql

C. tests:
- name: my_custom_test
test: my_custom_test

D. tests:
- my_custom_test

Solution

1. Step 1: Recall the schema.yml syntax for custom singular tests

   Custom singular tests are referenced by their filename (without .sql) in the tests list of schema.yml.

2. Step 2: Match options to this syntax

   tests: - my_custom_test correctly references the test file tests/my_custom_test.sql. Other options use incorrect structure, extra keys, or include .sql.

3. Final Answer:

   tests: - my_custom_test -> Option D

4. Quick Check:

   schema.yml test syntax = - test_filename_without_sql [OK]

Hint: Reference tests by name (no .sql) in tests: list [OK]

Common Mistakes:

• Using 'name' or 'test' keys
• Including .sql extension
• Using map/dict structure

3. Given the following custom singular test SQL in tests/check_positive_values.sql:

SELECT * FROM {{ ref('orders') }} WHERE amount <= 0

What will be the output if all amounts in the orders table are positive?

medium

A. An empty result with zero rows

B. A table with all rows where amount is less than or equal to zero

C. An error because of invalid SQL syntax

D. A count of rows with amount less than or equal to zero

Solution

1. Step 1: Understand the test SQL logic

   The test selects rows where amount is less than or equal to zero.

2. Step 2: Analyze the data condition

   If all amounts are positive, no rows satisfy the condition, so the query returns zero rows.

3. Final Answer:

   An empty result with zero rows -> Option A

4. Quick Check:

   All positive amounts means zero rows returned [OK]

Hint: No matching rows means test passes with empty output [OK]

Common Mistakes:

• Expecting a count instead of rows
• Thinking it returns all rows
• Assuming SQL syntax error

4. You wrote a custom singular test SQL file but when running dbt test, it fails with a syntax error. Which of the following is the most likely cause?

medium

A. The model referenced in {{ ref() }} does not exist

B. The test SQL returns zero rows

C. The SQL file is missing the required SELECT statement

D. The test is not listed in schema.yml

Solution

1. Step 1: Identify causes of SQL syntax errors

   Syntax errors happen when SQL is malformed, such as missing SELECT statements.

2. Step 2: Evaluate options for syntax error causes

   The SQL file is missing the required SELECT statement directly relates to SQL syntax. Other options cause runtime or configuration errors, not syntax errors.

3. Final Answer:

   The SQL file is missing the required SELECT statement -> Option C

4. Quick Check:

   Syntax error = malformed SQL like missing SELECT [OK]

Hint: Syntax errors usually mean SQL is incomplete or malformed [OK]

Common Mistakes:

• Confusing missing test listing with syntax error
• Assuming zero rows cause syntax errors
• Ignoring missing model references

5. You want to create a custom singular test that checks if any user has a NULL email in the users table. Which SQL query should you write in your test file?

hard

A. SELECT * FROM {{ ref('users') }} WHERE email IS NULL

B. SELECT COUNT(*) FROM {{ ref('users') }} WHERE email IS NULL

C. SELECT email FROM {{ ref('users') }} WHERE email IS NOT NULL

D. SELECT * FROM {{ ref('users') }} WHERE email = ''

Solution

1. Step 1: Understand the test goal

   The test should return rows where email is NULL to detect missing emails.

2. Step 2: Choose the SQL that returns rows with NULL emails

   SELECT * FROM {{ ref('users') }} WHERE email IS NULL returns rows only when there are NULL emails (0 rows = pass). COUNT(*) always returns one row, failing even with zero NULLs. IS NOT NULL selects good rows (opposite). = '' checks empty strings, not NULLs.

3. Final Answer:

   SELECT * FROM {{ ref('users') }} WHERE email IS NULL -> Option A

4. Quick Check:

   Return rows with NULL email = SELECT * FROM {{ ref('users') }} WHERE email IS NULL [OK]

Hint: Use SELECT * WHERE column IS NULL to find missing values [OK]

Common Mistakes:

• Using COUNT(*) instead of returning rows
• Checking for empty string instead of NULL
• Selecting non-NULL emails