dbt-expectations Setup and Configuration

dbt-expectations is a community package that brings 50+ pre-built data quality tests to any dbt project. It was ported from the Great Expectations Python library and is now maintained by Metaplane. Where dbt’s four built-in generic tests (unique, not_null, accepted_values, relationships) cover structural basics, dbt-expectations fills the gaps: pattern matching, statistical validation, freshness checks on any model, multi-column tests, and conditional filtering.

Installation

Add the package to your packages.yml with a version range pin:

packages:
  - package: metaplane/dbt_expectations
    version: [">=0.10.0", "<0.11.0"]

The version range pin (>=0.10.0, <0.11.0) is important. Pinning to an exact version means you miss patch fixes. Using an unbounded range risks pulling in breaking changes. The range pin gets you patches while protecting against major version bumps.

Timezone Configuration

dbt-expectations requires a timezone variable for any date-based test. Without this, tests like expect_row_values_to_have_recent_data will fail with a confusing compilation error rather than a clear “missing variable” message.

Add this to your dbt_project.yml:

vars:
  'dbt_date:time_zone': 'Europe/Paris'

Use the IANA timezone name that matches your business context. For a US-based company, 'America/New_York' or 'America/Los_Angeles'. For UTC-first teams, 'UTC'. This variable feeds the underlying dbt-date package, which dbt-expectations depends on for all temporal logic.

Dependencies

Running dbt deps after adding the package pulls in two transitive dependencies automatically:

• dbt-date — date utility macros (date spines, timezone handling, calendar generation)
• dbt-utils — the standard dbt utility package (if you don’t already have it)

You don’t need to declare these in your packages.yml separately. If you already have dbt-utils pinned to a specific version, check that the version range is compatible with what dbt-expectations requires. Version conflicts between dbt-utils ranges are the most common dbt deps failure when adding dbt-expectations to an existing project.

Platform Support

dbt-expectations requires dbt 1.8 or later and fully supports:

• BigQuery
• Snowflake
• Postgres
• Redshift
• DuckDB
• Trino

Most tests work identically across platforms. The exceptions are date-handling tests where SQL dialect differences (BigQuery’s DATE_SUB vs Snowflake’s DATEADD) are abstracted away by the package’s internal macros. You write the same YAML regardless of warehouse.

Verifying the Installation

After dbt deps, the quickest way to verify everything works is to add a single test to your most critical model and run it:

models:
  - name: your_most_important_mart
    columns:
      - name: created_at
        tests:
          - dbt_expectations.expect_row_values_to_have_recent_data:
              datepart: hour
              interval: 48

Run dbt test --select your_most_important_mart and confirm the test compiles and executes. If you get a compilation error about missing variables, the timezone configuration is missing. If you get a dependency error, run dbt deps again.

What You Get

With the package installed, you now have access to tests across several categories:

• Table-level tests — row count validation, freshness checks, cross-table comparisons
• Pattern validation — regex and LIKE pattern matching for format enforcement
• Value range validation — individual value bounds and statistical distribution checks
• Multi-column validation — composite key uniqueness and cross-column business rules
• Completeness tests — time series gap detection and data coverage verification

See dbt-expectations Test Reference for the full catalog with code examples, and dbt-expectations row_condition Pattern for the conditional filtering parameter that works across nearly all of these tests.

Where dbt-expectations Fits

dbt-expectations occupies the “known domain violations” layer in a data quality strategy. It catches problems you can anticipate and define rules for. It doesn’t replace native generic tests (which handle structural validation) or Elementary (which handles anomaly detection). The three work together:

In terms of setup sequence: dbt-expectations is a natural addition after basic generic tests are in place, covering domain validation that generic tests cannot express.