From d2915ab795503c92ce50faa79ffe86cf1c90f697 Mon Sep 17 00:00:00 2001 From: Joost Boonzajer Flaes Date: Sun, 30 Aug 2026 18:02:09 +0300 Subject: [PATCH 1/2] docs: cover the five new with_context tests and drop accepted_range Adds expression_is_true_with_context, not_empty_string_with_context, expect_column_pair_values_A_to_be_greater_than_B_with_context, expect_compound_columns_to_be_unique_with_context and expect_column_values_to_match_regex_list_with_context. Removes accepted_range_with_context, which no longer ships. Corrects two things that are no longer true. The regex test carried a "Requires dbt_expectations to be installed" note; the tests now use a native implementation and need no extra packages, so the intro says that explicitly. In its place the regex tests carry a warning that T-SQL has no regex functions, so they are unsupported on SQL Server and Fabric. Also notes that expression_is_true_with_context is table-level and therefore needs every wanted column listed under context_columns, which is the one non-obvious thing about it. Co-Authored-By: Claude Opus 5 --- docs/data-tests/with-context-tests.mdx | 220 ++++++++++++++++++++++--- 1 file changed, 194 insertions(+), 26 deletions(-) diff --git a/docs/data-tests/with-context-tests.mdx b/docs/data-tests/with-context-tests.mdx index 947e52c17..6094b6343 100644 --- a/docs/data-tests/with-context-tests.mdx +++ b/docs/data-tests/with-context-tests.mdx @@ -8,6 +8,12 @@ When a test fails, the failing rows are returned together with the columns you c If `context_columns` is omitted, **all columns** are returned alongside failing rows. + + No extra packages are required. These tests ship with the Elementary dbt + package and do not depend on `dbt_utils` or `dbt_expectations` being installed, + even where they mirror a test from one of those packages. + + If a column listed in `context_columns` does not exist on the model, a warning is logged and that column is skipped. The test continues and will not error. @@ -53,47 +59,86 @@ models: --- -## accepted_range_with_context +## expression_is_true_with_context + +`elementary.expression_is_true_with_context` -`elementary.accepted_range_with_context` +Validates that a SQL expression holds for every row. Extends `dbt_utils.expression_is_true`. -Validates that column values fall within an accepted range. Extends `dbt_utils.accepted_range`. +This is the most flexible test in the set: any condition you can write in SQL, including range checks and comparisons across columns. + + + This test is table-level, so it has no tested column of its own. List every + column you want in the sample under `context_columns`, including the ones your + expression references. + ### Parameters -| Parameter | Required | Default | Description | -| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------ | -| `column_name` | Yes | — | The column to test. | -| `min_value` | No* | `none` | Minimum accepted value (inclusive by default). At least one bound must be provided. | -| `max_value` | No* | `none` | Maximum accepted value (inclusive by default). At least one bound must be provided. | -| `inclusive` | No | `true` | Whether the bounds are inclusive. | -| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. | +| Parameter | Required | Default | Description | +| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- | +| `expression` | Yes | — | SQL condition that must hold for every row. Rows where it is false are returned. | +| `column_name` | No | `none` | Apply the expression to a single column, as in `column_name: amount` with `expression: "> 0"`. | +| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. | + + + +```yml Range check +models: + - name: orders + data_tests: + - elementary.expression_is_true_with_context: + expression: "amount >= 0 and amount <= 10000" + context_columns: [amount, order_id, customer_id] +``` + +```yml Comparison across columns +models: + - name: subscriptions + data_tests: + - elementary.expression_is_true_with_context: + expression: "end_date > start_date" + context_columns: [subscription_id, start_date, end_date] +``` + + + +--- + +## not_empty_string_with_context + +`elementary.not_empty_string_with_context` -\* At least one of `min_value` or `max_value` must be provided. +Validates that a column contains no empty strings. Extends `dbt_utils.not_empty_string`. + +### Parameters + +| Parameter | Required | Default | Description | +| ------------------ | -------- | ------- | ------------------------------------------------------------------------------- | +| `column_name` | Yes | — | The column to test. | +| `trim_whitespace` | No | `true` | Whether to trim the value before testing, so whitespace-only values also fail. | +| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. | ```yml With context columns models: - - name: orders + - name: customers columns: - - name: amount + - name: name data_tests: - - elementary.accepted_range_with_context: - min_value: 0 - max_value: 10000 - context_columns: [order_id, customer_id, order_date] + - elementary.not_empty_string_with_context: + context_columns: [customer_id, email, created_at] ``` -```yml Min bound only +```yml Treat whitespace-only values as valid models: - - name: orders + - name: customers columns: - - name: amount + - name: notes data_tests: - - elementary.accepted_range_with_context: - min_value: 0 - inclusive: false + - elementary.not_empty_string_with_context: + trim_whitespace: false ``` @@ -161,15 +206,83 @@ models: --- +## expect_compound_columns_to_be_unique_with_context + +`elementary.expect_compound_columns_to_be_unique_with_context` + +Expects a combination of columns to be unique. Returns every duplicate row, so you can see the full context of each collision. Extends `dbt_expectations.expect_compound_columns_to_be_unique`. + +Use this when no single column identifies a row, for example when uniqueness is on a customer and date pair. + +### Parameters + +| Parameter | Required | Default | Description | +| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- | +| `column_list` | Yes | — | List of columns whose combination must be unique. | +| `row_condition` | No | `none` | Optional SQL filter applied before testing. | +| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. | + + + +```yml With context columns +models: + - name: daily_metrics + data_tests: + - elementary.expect_compound_columns_to_be_unique_with_context: + column_list: [customer_id, metric_date] + context_columns: [metric_value, loaded_at] +``` + + + +--- + +## expect_column_pair_values_A_to_be_greater_than_B_with_context + +`elementary.expect_column_pair_values_A_to_be_greater_than_B_with_context` + +Expects the values of one column to be greater than another. Extends `dbt_expectations.expect_column_pair_values_A_to_be_greater_than_B`. + +Both compared columns are always returned with failing rows, before any `context_columns`. + +### Parameters + +| Parameter | Required | Default | Description | +| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- | +| `column_A` | Yes | — | The column expected to hold the greater value. | +| `column_B` | Yes | — | The column compared against. | +| `or_equal` | No | `false` | Whether equal values pass. | +| `row_condition` | No | `none` | Optional SQL filter applied before testing. | +| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. | + + + +```yml With context columns +models: + - name: orders + data_tests: + - elementary.expect_column_pair_values_A_to_be_greater_than_B_with_context: + column_A: total_amount + column_B: discount_amount + or_equal: true + context_columns: [order_id, customer_id] +``` + + + +--- + ## expect_column_values_to_match_regex_with_context `elementary.expect_column_values_to_match_regex_with_context` Expects column values to match a given regular expression. Extends `dbt_expectations.expect_column_values_to_match_regex`. - - Requires `dbt_expectations` to be installed in your project. - + + Not supported on SQL Server or Microsoft Fabric. T-SQL has no regular + expression functions, so this test raises a clear compilation error on those + platforms rather than running. + ### Parameters @@ -199,6 +312,61 @@ models: --- +## expect_column_values_to_match_regex_list_with_context + +`elementary.expect_column_values_to_match_regex_list_with_context` + +Expects column values to match any or all of a list of regular expressions. Extends `dbt_expectations.expect_column_values_to_match_regex_list`. + + + Not supported on SQL Server or Microsoft Fabric. T-SQL has no regular + expression functions, so this test raises a clear compilation error on those + platforms rather than running. + + +### Parameters + +| Parameter | Required | Default | Description | +| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- | +| `regex_list` | Yes | — | List of regular expression patterns. | +| `match_on` | No | `"any"` | `"any"` passes a row that matches at least one pattern, `"all"` requires every pattern. Any other value raises an error. | +| `row_condition` | No | `none` | Optional SQL filter applied before testing. | +| `is_raw` | No | `false` | Whether the patterns are raw strings. Only affects Snowflake and BigQuery. | +| `flags` | No | `""` | Optional regex flags. Flags the platform does not support are dropped with a warning. | +| `context_columns` | No | `none` | List of additional columns to return with failing rows. Omit to return all columns. | + + + +```yml Match any pattern +models: + - name: contacts + columns: + - name: phone + data_tests: + - elementary.expect_column_values_to_match_regex_list_with_context: + regex_list: + - "^\\+1[0-9]{10}$" + - "^\\+44[0-9]{10}$" + match_on: any + context_columns: [contact_id, country] +``` + +```yml Require every pattern +models: + - name: products + columns: + - name: sku + data_tests: + - elementary.expect_column_values_to_match_regex_list_with_context: + regex_list: ["^SKU-", "-[0-9]+$"] + match_on: all + context_columns: [product_id, name] +``` + + + +--- + ## relationships_with_context `elementary.relationships_with_context` From 917cdbf669f0ae8169517753ed703e489391c9b9 Mon Sep 17 00:00:00 2001 From: Joost Boonzajer Flaes Date: Thu, 3 Sep 2026 18:36:30 +0300 Subject: [PATCH 2/2] docs: document accepted_range_with_context as deprecated, not removed The page had removed it outright, which no longer matches the package: it now ships as a deprecated test that logs a warning and is scheduled for removal in the next release. Published docs and the stored test description disagreed. Adds it back at the end of the page, marked deprecated, with the migration to dbt_utils.accepted_range and a pointer to the sampling controls for the one thing it could do that the replacement cannot: narrowing a stored sample. Co-Authored-By: Claude Opus 5 --- docs/data-tests/with-context-tests.mdx | 45 ++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/data-tests/with-context-tests.mdx b/docs/data-tests/with-context-tests.mdx index 6094b6343..b0d7088f9 100644 --- a/docs/data-tests/with-context-tests.mdx +++ b/docs/data-tests/with-context-tests.mdx @@ -408,3 +408,48 @@ models: ``` + + +--- + +## accepted_range_with_context + +`elementary.accepted_range_with_context` + + + Deprecated, and scheduled for removal in the next release. Use + `dbt_utils.accepted_range` instead. Running it logs a warning. + + +`dbt_utils.accepted_range` selects every column already, so unlike the other +tests on this page this one cannot add context to a stored sample. The only +thing it can do is narrow the sample to a chosen subset, which is not what +`context_columns` is for. + +If you were using it to keep columns out of a stored sample, there is no direct +replacement. Use the sampling controls instead: the `show_sample_rows` and PII +tags, `disable_test_samples`, or `test_sample_row_count`. + +### Migration + +```yml Before +models: + - name: orders + columns: + - name: amount + data_tests: + - elementary.accepted_range_with_context: + min_value: 0 + max_value: 10000 +``` + +```yml After +models: + - name: orders + columns: + - name: amount + data_tests: + - dbt_utils.accepted_range: + min_value: 0 + max_value: 10000 +```