{"id":3987,"library":"elementary-data","title":"Elementary Data","description":"Elementary Data is an open-source Python library and CLI tool that provides dbt-native data observability, including data monitoring, lineage, and data quality checks. It works in conjunction with the Elementary dbt package to collect metadata and generate comprehensive reports and alerts from your data warehouse. Currently at version 0.23.1, the library maintains an active release cadence with frequent updates and improvements.","status":"active","version":"0.23.1","language":"en","source_language":"en","source_url":"https://github.com/elementary-data/elementary","tags":["data monitoring","data lineage","dbt","data observability","data quality","analytics engineering"],"install":[{"cmd":"pip install elementary-data","lang":"bash","label":"Base installation for CLI"},{"cmd":"pip install 'elementary-data[all]'","lang":"bash","label":"Installation with all database connectors"},{"cmd":"pip install 'elementary-data[snowflake]' # Or bigquery, redshift, databricks, etc.","lang":"bash","label":"Installation for specific database"}],"dependencies":[{"reason":"Elementary Data works by integrating with dbt projects and reading dbt artifacts and test results. It requires a dbt package (`elementary-data/elementary`) to be installed in your dbt project.","package":"dbt-core","optional":false},{"reason":"Used for data validation and schema definition within the library. Compatibility issues have occurred in the past, particularly around major version transitions.","package":"pydantic","optional":false}],"imports":[],"quickstart":{"code":"# 1. Install the Elementary dbt package (in your dbt project's packages.yml):\n# packages:\n#   - package: elementary-data/elementary\n#     version: 0.23.0 # Use the latest version\n\n# 2. Add configuration to your dbt_project.yml (example):\n# models:\n#   elementary:\n#     +schema: \"elementary\"\n\n# 3. Install dbt dependencies and build Elementary models:\n# dbt deps\n# dbt run --select elementary\n# dbt test\n\n# 4. Install the Elementary CLI:\npip install elementary-data\n\n# 5. Ensure your dbt profiles.yml is configured with an 'elementary' profile\n# (see Elementary docs for details, typically ~/.dbt/profiles.yml)\n\n# 6. Generate the data observability report:\n# The report will be saved as an HTML file in 'target/elementary_report.html'\nedr report --project-dir $(pwd)\n\n# Or to monitor and send alerts:\n# edr monitor --slack-token $SLACK_TOKEN --slack-channel '#data-alerts'\n","lang":"bash","description":"The `elementary-data` library's primary function is accessed via its command-line interface (`edr`), which generates data observability reports and sends alerts based on dbt project artifacts. This quickstart assumes you have an active dbt project with the Elementary dbt package configured and run. The `edr report` command will then query your data warehouse (via your dbt profiles) and generate a comprehensive HTML report."},"warnings":[{"fix":"Ensure both the `elementary-data` Python library and the `elementary-data/elementary` dbt package are updated to compatible versions as recommended in Elementary's documentation. Regularly check release notes for specific version compatibility information.","message":"The `elementary-data` Python CLI works in conjunction with the `elementary-data/elementary` dbt package. Frequent updates to the dbt package can introduce incompatibilities if the CLI and dbt package versions are not aligned. Always refer to the official documentation for recommended version pairings.","severity":"breaking","affected_versions":"All versions, due to inter-package dependencies"},{"fix":"Migrate any custom code that interacts with `datetime.utcnow()` to `datetime.now(tz=timezone.utc)` to ensure timezone-aware operations and avoid future deprecation warnings.","message":"In version 0.23.0, `datetime.utcnow()` was replaced with `datetime.now(tz=timezone.utc)` for compliance with Python's best practices regarding timezone-aware datetimes. Code directly interacting with Elementary's internal datetime handling might need updating.","severity":"deprecated","affected_versions":">=0.23.0"},{"fix":"Keep `elementary-data` updated to the latest version to benefit from Pydantic compatibility fixes. When encountering Pydantic errors, check if other installed libraries have conflicting Pydantic version requirements. Consider using tools like `pipdeptree` or `pydantic-compat` for complex dependency environments.","message":"While v0.19.2 addressed a specific backwards compatibility issue with Pydantic, broader Pydantic major version transitions (e.g., v1 to v2) can still cause issues if other libraries in your environment have conflicting Pydantic versions. This can lead to unexpected runtime errors.","severity":"gotcha","affected_versions":"<0.19.2, and potentially any version in environments with mixed Pydantic dependencies."},{"fix":"Upgrade `elementary-data` to version 0.20.0 or higher to ensure compatibility with updated dbt command structures.","message":"Elementary updated its internal dbt usage in v0.20.0 to remove the deprecated `-m` flag. Users running older versions of `elementary-data` with newer `dbt` versions might experience unexpected behavior or errors related to dbt command execution.","severity":"gotcha","affected_versions":"<0.20.0 when used with newer dbt versions"},{"fix":"Ensure your `~/.dbt/profiles.yml` file contains a profile named `elementary` with valid credentials and connection details for your data warehouse. Refer to Elementary's documentation for required permissions and specific database configurations.","message":"The `edr` CLI requires a correctly configured `profiles.yml` (following dbt's format) with a profile specifically named `elementary` to connect to your data warehouse. Misconfiguration of this profile is a common cause of connection issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `elementary-data` to version 0.19.4 or later to resolve the JSON serialization issue for `inf` and `nan` float values.","message":"Prior to v0.19.4, `float(\"inf\")` (infinity) and `float(\"nan\")` (not a number) values in your data could cause JSON serialization failures when `elementary-data` attempted to generate reports, leading to corrupted or ungeneratable output.","severity":"gotcha","affected_versions":"<0.19.4"},{"fix":"Understand the distinct roles: `elementary-data` (CLI, `edr`) for dbt-native report generation and alerts from your data warehouse, and `elementary_sdk` (Python API) for integrating Python-based data quality checks with Elementary Cloud. Use the appropriate tool for your specific need.","message":"The `elementary_sdk` Python package (distinct from `elementary-data` CLI) is primarily for programmatically sending data quality information to Elementary Cloud and testing Python pipelines. It's not intended for generating the self-hosted reports that the `edr` CLI provides. Confusing their purposes or expecting CLI features from the SDK (or vice-versa) can lead to integration challenges.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}