When a test fails, Elementary captures a sample of the failing rows and stores them in the test_result_rows table. These samples help you quickly understand and investigate data issues without manually running queries.
By default, Elementary saves 5 sample rows per failed test.
This page describes all the available controls for managing test result samples — both self-service configuration in your dbt project and options available through the Elementary team for Cloud users.
Configuring sample size
Global setting
Set the number of sample rows saved per failed test across your entire project by adding the test_sample_row_count variable to your dbt_project.yml:
vars:
test_sample_row_count: 10
dbt test --vars '{"test_sample_row_count": 10}'
0 to disable sample collection entirely:
vars:
test_sample_row_count: 0
The larger the number of rows you save, the more data you will store in your data warehouse. This can affect the performance and cost of your Elementary schema, depending on your database.
Per-test override
You can override the global sample size for individual tests using the test_sample_row_count meta configuration:
models:
- name: orders
data_tests:
- unique:
config:
meta:
test_sample_row_count: 20 # Save more samples for this specific test
- not_null:
column_name: order_id
config:
meta:
test_sample_row_count: 0 # Disable samples for this test
Disabling samples for specific tests
Use the disable_test_samples meta configuration to completely disable sample collection for a specific test:
models:
- name: user_profiles
data_tests:
- elementary.volume_anomalies:
config:
meta:
disable_test_samples: true
PII protection
Elementary provides built-in protection for sensitive data by automatically disabling test sample collection when a PII tag is detected.
Enable PII protection
Add these variables to your dbt_project.yml:
vars:
disable_samples_on_pii_tags: true # Enable PII protection (default: false)
pii_tags: ['pii', 'sensitive'] # Tags that identify PII data (default: ['pii'])
PII, pii, and Pii are all equivalent.
Tag levels
PII tags are evaluated at three levels:
Model level — disables samples for all tests on that model:
models:
- name: customer_data
config:
tags: ['pii']
models:
- name: customer_data
columns:
- name: email
tags: ['pii']
models:
- name: customer_data
data_tests:
- elementary.volume_anomalies:
config:
tags: ['pii']
dbt_project.yml:
models:
my_project:
sensitive_data:
+tags: ['pii']
Showing samples selectively with show_sample_rows
show_sample_rows is the inverse of PII protection. When enabled, all samples are hidden by default and only shown for models, columns, or tests that are explicitly tagged.
Enable selective sample display
vars:
enable_samples_on_show_sample_rows_tags: true # Hide all samples by default (default: false)
show_sample_rows is used to opt in. You can customize this with the show_sample_rows_tags variable — just like pii_tags lets you customize which tags trigger PII protection:
vars:
enable_samples_on_show_sample_rows_tags: true
show_sample_rows_tags: ['show_sample_rows', 'debug'] # default: ['show_sample_rows']
Tag levels
Works at the same three levels as PII:
Model level — shows samples for all tests on that model:
models:
- name: orders
config:
tags: ['show_sample_rows']
models:
- name: orders
columns:
- name: status
tags: ['show_sample_rows']
models:
- name: orders
data_tests:
- elementary.volume_anomalies:
config:
tags: ['show_sample_rows']
Behavior matrix
| Level | Tags | Samples shown? |
|---|
| model | none | No (hidden by default) |
| model | show_sample_rows | Yes |
| model | pii | No (hidden by default) |
| test | show_sample_rows | Yes |
| column | show_sample_rows | Yes |
| Level | Tags | Samples shown? |
|---|
| model | none | Yes |
| model | pii | No |
| test | pii | No |
| column | pii | No |
| column | show_sample_rows (no pii) | Yes (excluded from PII columns) |
Configuration precedence
When multiple settings apply, Elementary follows this order (highest priority first):
disable_test_samples in test meta — per-test on/off switchshow_sample_rows tag — when enable_samples_on_show_sample_rows_tags: true and the model, column, or test has a matching tagenable_samples_on_show_sample_rows_tags — hides all samples by default when enabled- PII tag detection — when
disable_samples_on_pii_tags: true and the model, column, or test has a matching tag
test_sample_row_count global var — project-wide sample size- Default — 5 rows
Elementary Cloud: additional controls
For Elementary Cloud users, there are additional environment-level controls that can be enabled by the Elementary team.
The controls below are managed by Elementary and apply to how test samples are handled after they are synced from your data warehouse. To request changes, contact the Elementary team via Slack or email.
Disable test samples for an environment
The Elementary team can disable test samples entirely for a specific environment. When enabled:
- Test samples will not be synced from your Elementary schema.
- Test samples will not appear in the UI or in alerts, even if they exist in your warehouse.
This is useful for environments that contain highly sensitive data where no sample rows should ever leave the warehouse.
Skip database storage of sample rows
The Elementary team can configure an environment so that the test_result_rows data is stored only in the data lake (S3) and not loaded into the application database. This reduces database size while keeping the raw data available for debugging if needed.
Summary of all controls
| Control | Scope | Where to configure | Default |
|---|
test_sample_row_count | Global | dbt_project.yml vars | 5 |
test_sample_row_count | Per-test | Test meta | Inherits global |
disable_test_samples | Per-test | Test meta | false |
disable_samples_on_pii_tags | Global | dbt_project.yml vars | false |
pii_tags | Global | dbt_project.yml vars | ['pii'] |
enable_samples_on_show_sample_rows_tags | Global | dbt_project.yml vars | false |
show_sample_rows_tags | Global | dbt_project.yml vars | ['show_sample_rows'] |
| Disable samples for environment | Per-environment | Contact Elementary team | Disabled |
| Skip DB storage of sample rows | Per-environment | Contact Elementary team | Disabled |
