Skip to content

Commit bad3197

Browse files
joostboonclaude
joostboon
and
claude
committed
docs: add with-context tests documentation
Documents the six new elementary generic tests that return context columns alongside failing rows: not_null_with_context, accepted_range_with_context, expect_column_values_to_not_be_null_with_context, expect_column_values_to_be_unique_with_context, expect_column_values_to_match_regex_with_context, relationships_with_context. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent b4d3183 commit bad3197

2 files changed

Lines changed: 244 additions & 1 deletion

File tree

‎docs/data-tests/with-context-tests.mdx‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: "Tests with context"
3+
sidebarTitle: "Tests with context"
4+
---
5+
6+
A set of generic tests that extend common dbt, dbt-utils, and dbt-expectations tests with a `context_columns` parameter.
7+
When a test fails, the failing rows are returned together with the columns you care about — making it much easier to investigate the root cause directly from the test results.
8+
9+
If `context_columns` is omitted, **all columns** are returned alongside failing rows.
10+
11+
<Note>
12+
If a column listed in `context_columns` does not exist on the model, a warning
13+
is logged and that column is skipped. The test continues and will not error.
14+
</Note>
15+
16+
---
17+
18+
## not_null_with_context
19+
20+
`elementary.not_null_with_context`
21+
22+
Validates that there are no null values in a column. Extends dbt's built-in `not_null` test.
23+
24+
### Parameters
25+
26+
| Parameter | Required | Default | Description |
27+
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- |
28+
| `column_name` | Yes | — | The column to test for null values. |
29+
| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. |
30+
31+
<RequestExample>
32+
33+
```yml With context columns
34+
models:
35+
- name: orders
36+
columns:
37+
- name: order_id
38+
data_tests:
39+
- elementary.not_null_with_context:
40+
context_columns: [customer_id, order_date, amount]
41+
```
42+
43+
```yml Return all columns
44+
models:
45+
- name: orders
46+
columns:
47+
- name: order_id
48+
data_tests:
49+
- elementary.not_null_with_context
50+
```
51+
52+
</RequestExample>
53+
54+
---
55+
56+
## accepted_range_with_context
57+
58+
`elementary.accepted_range_with_context`
59+
60+
Validates that column values fall within an accepted range. Extends `dbt_utils.accepted_range`.
61+
62+
### Parameters
63+
64+
| Parameter | Required | Default | Description |
65+
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------ |
66+
| `column_name` | Yes | — | The column to test. |
67+
| `min_value` | No* | `none` | Minimum accepted value (inclusive by default). At least one bound must be provided. |
68+
| `max_value` | No* | `none` | Maximum accepted value (inclusive by default). At least one bound must be provided. |
69+
| `inclusive` | No | `true` | Whether the bounds are inclusive. |
70+
| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. |
71+
72+
\* At least one of `min_value` or `max_value` must be provided.
73+
74+
<RequestExample>
75+
76+
```yml With context columns
77+
models:
78+
- name: orders
79+
columns:
80+
- name: amount
81+
data_tests:
82+
- elementary.accepted_range_with_context:
83+
min_value: 0
84+
max_value: 10000
85+
context_columns: [order_id, customer_id, order_date]
86+
```
87+
88+
```yml Min bound only
89+
models:
90+
- name: orders
91+
columns:
92+
- name: amount
93+
data_tests:
94+
- elementary.accepted_range_with_context:
95+
min_value: 0
96+
inclusive: false
97+
```
98+
99+
</RequestExample>
100+
101+
---
102+
103+
## expect_column_values_to_not_be_null_with_context
104+
105+
`elementary.expect_column_values_to_not_be_null_with_context`
106+
107+
Expects column values to not be null. Extends `dbt_expectations.expect_column_values_to_not_be_null`.
108+
109+
### Parameters
110+
111+
| Parameter | Required | Default | Description |
112+
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- |
113+
| `column_name` | Yes | — | The column to test for null values. |
114+
| `row_condition` | No | `none` | Optional SQL filter applied before testing (e.g. `"status = 'active'"`). |
115+
| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. |
116+
117+
<RequestExample>
118+
119+
```yml With row condition and context columns
120+
models:
121+
- name: subscriptions
122+
columns:
123+
- name: end_date
124+
data_tests:
125+
- elementary.expect_column_values_to_not_be_null_with_context:
126+
row_condition: "status = 'active'"
127+
context_columns: [subscription_id, customer_id, start_date]
128+
```
129+
130+
</RequestExample>
131+
132+
---
133+
134+
## expect_column_values_to_be_unique_with_context
135+
136+
`elementary.expect_column_values_to_be_unique_with_context`
137+
138+
Expects column values to be unique. Returns all duplicate rows (not just a count), so you can see the full context of each duplicate. Extends `dbt_expectations.expect_column_values_to_be_unique`.
139+
140+
### Parameters
141+
142+
| Parameter | Required | Default | Description |
143+
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- |
144+
| `column_name` | Yes | — | The column to test for uniqueness. |
145+
| `row_condition` | No | `none` | Optional SQL filter applied before testing. |
146+
| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. |
147+
148+
<RequestExample>
149+
150+
```yml With context columns
151+
models:
152+
- name: customers
153+
columns:
154+
- name: email
155+
data_tests:
156+
- elementary.expect_column_values_to_be_unique_with_context:
157+
context_columns: [customer_id, created_at, name]
158+
```
159+
160+
</RequestExample>
161+
162+
---
163+
164+
## expect_column_values_to_match_regex_with_context
165+
166+
`elementary.expect_column_values_to_match_regex_with_context`
167+
168+
Expects column values to match a given regular expression. Extends `dbt_expectations.expect_column_values_to_match_regex`.
169+
170+
<Info>
171+
Requires `dbt_expectations` to be installed in your project.
172+
</Info>
173+
174+
### Parameters
175+
176+
| Parameter | Required | Default | Description |
177+
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- |
178+
| `column_name` | Yes | — | The column to test. |
179+
| `regex` | Yes | — | The regular expression pattern to match. |
180+
| `row_condition` | No | `none` | Optional SQL filter applied before testing. |
181+
| `is_raw` | No | `false` | Whether the regex is a raw string. |
182+
| `flags` | No | `""` | Optional regex flags (adapter-dependent). |
183+
| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. |
184+
185+
<RequestExample>
186+
187+
```yml Email format validation with context
188+
models:
189+
- name: customers
190+
columns:
191+
- name: email
192+
data_tests:
193+
- elementary.expect_column_values_to_match_regex_with_context:
194+
regex: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
195+
context_columns: [customer_id, name, created_at]
196+
```
197+
198+
</RequestExample>
199+
200+
---
201+
202+
## relationships_with_context
203+
204+
`elementary.relationships_with_context`
205+
206+
Validates referential integrity between a child and parent table. Extends dbt's built-in `relationships` test.
207+
208+
### Parameters
209+
210+
| Parameter | Required | Default | Description |
211+
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- |
212+
| `column_name` | Yes | — | The foreign key column in the child model. |
213+
| `to` | Yes | — | The parent model (use `ref()` or `source()`). |
214+
| `field` | Yes | — | The column in the parent model to join to. |
215+
| `context_columns` | No | `none` | List of additional columns from the child model to return with failing rows. Omit to return all columns. |
216+
217+
<RequestExample>
218+
219+
```yml With context columns
220+
models:
221+
- name: orders
222+
columns:
223+
- name: customer_id
224+
data_tests:
225+
- elementary.relationships_with_context:
226+
to: ref('customers')
227+
field: id
228+
context_columns: [order_id, order_date, amount]
229+
```
230+
231+
```yml Return all columns
232+
models:
233+
- name: orders
234+
columns:
235+
- name: customer_id
236+
data_tests:
237+
- elementary.relationships_with_context:
238+
to: ref('customers')
239+
field: id
240+
```
241+
242+
</RequestExample>

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -423,7 +423,8 @@
423423
"data-tests/python-tests",
424424
"data-tests/execution-sla",
425425
"data-tests/data-freshness-sla",
426-
"data-tests/volume-threshold"
426+
"data-tests/volume-threshold",
427+
"data-tests/with-context-tests"
427428
]
428429
},
429430
{

0 commit comments

Comments
 (0)