Elementary installation involves two distinct systems: a dbt package that runs during dbt run and dbt test executions, and a standalone CLI (edr) that reads from the tables the package creates. Each has its own configuration. This hub covers the full setup sequence, including the steps most commonly missed.
Understanding what you’re installing
Before touching a config file, Elementary for dbt explains the architecture: the dbt package creates metadata tables via on-run-end hooks, and the CLI (edr) reads those tables to generate reports and send alerts. Understanding the separation helps diagnose problems later — if reports are empty, you can immediately narrow it to either “the package isn’t capturing results” or “the CLI can’t connect to the tables.”
Installing the dbt package
The package installation itself is straightforward: add it to packages.yml, configure its schema in dbt_project.yml, run dbt deps. Elementary for dbt covers the YAML.
What that note covers briefly but deserves its own attention: the materialization override. On dbt 1.8+, you also need to create a macro in your own project’s macros/ directory. Without it, tests run without errors but Elementary’s result tables stay empty. Elementary dbt Materialization Override explains why dbt 1.8 changed how package materializations work and exactly what you need to write.
Configuring the CLI profile
The CLI uses ~/.edr/profiles.yml, not your dbt profile. Start by running dbt run-operation elementary.generate_elementary_cli_profile to get a pre-filled template, then customize it for your warehouse.
Elementary CLI profile configuration covers the complete profile setup for BigQuery, Snowflake, and Databricks. The BigQuery section is worth reading carefully even if you think you have it right — the location parameter is the single most common cause of CLI connection errors, and it’s easy to miss because dbt infers it automatically but Elementary does not.
When things don’t work
If your report is empty after completing setup, Elementary setup troubleshooting has a diagnosis path. The failure modes are predictable: missing materialization override, location parameter missing from the BigQuery profile, Elementary tables accidentally materialized as views due to a conflicting project config. Each has a specific fix.
After setup
Once Elementary is capturing test results and you can generate a report, the next steps are anomaly detection tests and alerting. Those are covered in Elementary for dbt under the anomaly detection and alerting sections — volume anomaly detection in particular is worth adding early, because it catches failures that no other test type notices.
For context on where Elementary fits relative to other observability tools, Data Observability Tool Landscape covers the full option set. Data Observability Minimum Viable Stack describes the four capabilities worth implementing first, with Elementary providing two of them.