Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.elementary-data.com/llms.txt

Use this file to discover all available pages before exploring further.

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
Or pass it as a flag when running dbt: 
dbt test --vars '{"test_sample_row_count": 10}'
Set to 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
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: 
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 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: 
models:
  - name: customer_data
    config:
      tags: ['pii']
Column level — disables samples for tests that reference that column: 
models:
  - name: customer_data
    columns:
      - name: email
        tags: ['pii']
Test level — disables samples for that specific test: 
models:
  - name: customer_data
    data_tests:
      - elementary.volume_anomalies:
          config:
            tags: ['pii']
You can also tag entire directories in 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)
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: 
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: 
models:
  - name: orders
    config:
      tags: ['show_sample_rows']
Column level — shows samples for tests that target that column: 
models:
  - name: orders
    columns:
      - name: status
        tags: ['show_sample_rows']
Test level — shows samples for that specific test: 
models:
  - name: orders
    data_tests:
      - elementary.volume_anomalies:
          config:
            tags: ['show_sample_rows']

​
Behavior matrix

​
enable_samples_on_show_sample_rows_tags: true

LevelTagsSamples shown?
modelnoneNo (hidden by default)
modelshow_sample_rowsYes
modelpiiNo (hidden by default)
testshow_sample_rowsYes
columnshow_sample_rowsYes

​
disable_samples_on_pii_tags: true

LevelTagsSamples shown?
modelnoneYes
modelpiiNo
testpiiNo
columnpiiNo
columnshow_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

ControlScopeWhere to configureDefault
test_sample_row_countGlobaldbt_project.yml vars5
test_sample_row_countPer-testTest metaInherits global
disable_test_samplesPer-testTest metafalse
disable_samples_on_pii_tagsGlobaldbt_project.yml varsfalse
pii_tagsGlobaldbt_project.yml vars['pii']
enable_samples_on_show_sample_rows_tagsGlobaldbt_project.yml varsfalse
show_sample_rows_tagsGlobaldbt_project.yml vars['show_sample_rows']
Disable samples for environmentPer-environmentContact Elementary teamDisabled
Skip DB storage of sample rowsPer-environmentContact Elementary teamDisabled