> ## Documentation Index
> Fetch the complete documentation index at: https://elementary-devin-1782754750-bigquery-permissions-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Test Result Samples
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`:
```yaml theme={null}
vars:
test_sample_row_count: 10
```
Or pass it as a flag when running dbt:
```shell theme={null}
dbt test --vars '{"test_sample_row_count": 10}'
```
Set to `0` to disable sample collection entirely:
```yaml theme={null}
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:
```yaml theme={null}
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
```
The per-test setting takes precedence over the global variable.
## Disabling samples for specific tests
Use the `disable_test_samples` meta configuration to completely disable sample collection for a specific test:
```yaml theme={null}
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`:
```yaml theme={null}
vars:
disable_samples_on_pii_tags: true # Enable PII protection (default: false)
pii_tags: ['pii', 'sensitive'] # Tags that identify PII data (default: ['pii'])
```
PII tag matching is **case-insensitive** -- `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:
```yaml theme={null}
models:
- name: customer_data
config:
tags: ['pii']
```
**Column level** -- disables samples for tests that reference that column:
```yaml theme={null}
models:
- name: customer_data
columns:
- name: email
tags: ['pii']
```
**Test level** -- disables samples for that specific test:
```yaml theme={null}
models:
- name: customer_data
data_tests:
- elementary.volume_anomalies:
config:
tags: ['pii']
```
You can also tag entire directories in `dbt_project.yml`:
```yaml theme={null}
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
```yaml theme={null}
vars:
enable_samples_on_show_sample_rows_tags: true # Hide all samples by default (default: false)
```
By default, the tag `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:
```yaml theme={null}
vars:
enable_samples_on_show_sample_rows_tags: true
show_sample_rows_tags: ['show_sample_rows', 'debug'] # default: ['show_sample_rows']
```
Tag matching is **case-insensitive**.
### Tag levels
Works at the same three levels as PII:
**Model level** -- shows samples for all tests on that model:
```yaml theme={null}
models:
- name: orders
config:
tags: ['show_sample_rows']
```
**Column level** -- shows samples for tests that target that column:
```yaml theme={null}
models:
- name: orders
columns:
- name: status
tags: ['show_sample_rows']
```
**Test level** -- shows samples for that specific test:
```yaml theme={null}
models:
- name: orders
data_tests:
- elementary.volume_anomalies:
config:
tags: ['show_sample_rows']
```
## Behavior matrix
### `enable_samples_on_show_sample_rows_tags: true`
| 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 |
### `disable_samples_on_pii_tags: true`
| 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):
1. **`disable_test_samples` in test meta** -- per-test on/off switch
2. **`show_sample_rows` tag** -- when `enable_samples_on_show_sample_rows_tags: true` and the model, column, or test has a matching tag
3. **`enable_samples_on_show_sample_rows_tags`** -- hides all samples by default when enabled
4. **PII tag detection** -- when `disable_samples_on_pii_tags: true` and the model, column, or test has a matching tag
5. **`test_sample_row_count` global var** -- project-wide sample size
6. **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 |