Skip to main content

dbt-score

CI PyPI version PyPI license Docs PyPI - Python Version PRs Welcome

A comprehensive linter for dbt metadata that helps maintain high-quality data models at scale.

dbt-score lint
🥉 Model: orders (score: 2.7)
  WARN (medium) dbt_score.rules.generic.columns_have_description: Columns lack a description: customer_id, customer_name.
  WARN (high) dbt_score.rules.generic.has_description: Model lacks a description.
  WARN (medium) dbt_score.rules.generic.has_owner: Model lacks an owner.
  WARN (medium) dbt_score.rules.generic.sql_has_reasonable_number_of_lines: SQL query too long: 238 lines (> 200).
  WARN (medium) dbt_score_rules.custom_rules.has_test: Model lacks a test.

What is dbt-score?

dbt-score is a powerful linting tool designed to evaluate and score dbt (Data Build Tool) models based on metadata quality. It helps data teams maintain consistent standards across dbt projects by programmatically enforcing best practices for documentation, testing, naming conventions, and more.

Key Features

  • 🔍 Comprehensive Linting: Evaluates dbt entities against configurable rules for documentation, tests, naming, and structure
  • 📊 Scoring System: Provides numerical scores (0-10) for individual models and overall project health
  • 🎯 Flexible Configuration: Customizable rules, severity levels, and scoring thresholds via pyproject.toml
  • 🚀 CI/CD Integration: Fail builds when quality standards aren't met
  • 📈 Progress Tracking: Visual badges and scoring to track data quality improvements over time
  • 🔧 Extensible: Create custom rules tailored to organization-specific needs

Quick Start

Installation

pip install dbt-score

Note: Install dbt-score in the same environment as dbt-core.

Basic Usage

Run dbt-score from your dbt project root:

# Basic linting
dbt-score lint

# Also show passing tests
dbt-score lint --show all

# Lint specific models
dbt-score lint --select +my_model+

# Exclude specific models
dbt-score lint --exclude my_model+

# Auto-generate manifest (via `dbt parse`) and lint
dbt-score lint --run-dbt-parse

Example Output

dbt-score lint --show all
🥉 Model: orders (score: 2.7)
  WARN (medium) dbt_score.rules.generic.columns_have_description: Columns lack a description: customer_id, customer_name.
  WARN (high) dbt_score.rules.generic.has_description: Model lacks a description.
  WARN (medium) dbt_score.rules.generic.has_owner: Model lacks an owner.
  WARN (medium) dbt_score.rules.generic.sql_has_reasonable_number_of_lines: SQL query too long: 238 lines (> 200).
  WARN (medium) dbt_score_rules.custom_rules.has_test: Model lacks a test.

🥇 Model: customers (score: 10.0)
  OK    dbt_score.rules.generic.columns_have_description
  OK    dbt_score.rules.generic.has_description
  OK    dbt_score.rules.generic.has_owner
  OK    dbt_score.rules.generic.sql_has_reasonable_number_of_lines
  OK    dbt_score_rules.custom_rules.has_test

Project score: 6.3 🥈

Configuration

Configure dbt-score via pyproject.toml in the dbt project root:

[tool.dbt-score]
# Fail CI if project score falls below threshold
fail_project_under = 7.5
fail_any_item_under = 8.0

# Disable specific rules
disabled_rules = ["dbt_score.rules.generic.columns_have_description"]

# Configure badges
[tool.dbt-score.badges]
first.threshold = 10.0
first.icon = "🥇"
second.threshold = 8.0
second.icon = "🥈"
third.threshold = 6.0
third.icon = "🥉"
wip.icon = "🏗️"

# Customize rule severity and parameters
[tool.dbt-score.rules."dbt_score.rules.generic.sql_has_reasonable_number_of_lines"]
severity = 1
max_lines = 300

Why Use dbt-score?

As dbt projects grow to hundreds or thousands of models, maintaining consistent metadata becomes increasingly challenging:

  • Inconsistent Documentation: Some models are well-documented, others lack basic descriptions
  • Missing Tests: Critical models without proper data quality tests
  • Naming Inconsistencies: Models that don't follow established conventions
  • Technical Debt: Long, complex SQL queries that are hard to maintain
  • Compliance Issues: Missing ownership or governance metadata

dbt-score addresses these challenges by:

  • Automated Quality Checks: Continuously evaluate dbt projects against best practices
  • Objective Scoring: Get clear, numerical feedback on model quality
  • Team Alignment: Establish shared standards across data teams
  • CI/CD Integration: Prevent quality regressions in production

Built-in Rules

dbt-score comes with a small set of rules covering needs applicable to most dbt projects.

Advanced Usage

Custom Rules

Create organization-specific rules by writing simple Python functions:

from dbt_score import Model, rule, RuleViolation

@rule
def model_has_business_owner(model: Model) -> RuleViolation:
    if model.meta.get("business_owner") is None:
        return RuleViolation("Model lacks a business owner.")

CI/CD Integration

Add dbt-score to CI pipelines:

- name: Run dbt-score
  run: |
    dbt-score lint --run-dbt-parse

or equivalent in your favourite CI platform. dbt-score exits with 0 or 1 to signal success or failure, making integrations a breeze!

Selective Linting

Use dbt's selection and/or exclusion syntax to lint specific parts of projects:

# Lint only staging models
dbt-score lint --select staging.*

# Lint a model and its dependencies
dbt-score lint --select +my_important_model

# Lint recently changed models
dbt-score lint --select state:modified

# Lint all models except experimental ones
dbt-score lint --exclude my_experimental_model+

Documentation

For comprehensive documentation, including detailed rule descriptions, configuration options, and advanced usage patterns, visit the dbt-score documentation website.

Contributing

Contributions are welcome! This includes:

  • Reporting bugs or requesting features
  • Improving documentation
  • Adding new rules or formatters
  • Fixing issues

Check out the contributing guide to get started. 🚀

Requirements

  • Python 3.11+
  • dbt-core 1.5+

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.


Metadata

Release files for dbt-score 0.19.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbt-score 0.19.0
File Size Uploaded Provenance Actions
dbt_score-0.19.0.tar.gz 186.3 kB Without provenance Details for dbt_score-0.19.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dbt-score 0.19.0
File Interpreter ABI Platform Actions
dbt_score-0.19.0-py3-none-any.whl Python 3 none any Details for dbt_score-0.19.0-py3-none-any.whl

Total release size: 223.0 kB

Release files / dbt_score-0.19.0.tar.gz

Download URL dbt_score-0.19.0.tar.gz
Size 186.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1f3d6d6209031aad4b90571a17106efbc401877fd5c689a8ff6a3045ee99c95c
BLAKE2b-256 checksum
How to use checksums
47461fcbfd7a07451e91fc2b1a34e46996685685f1dceb35462da93b23aaf13b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / dbt_score-0.19.0-py3-none-any.whl

Download URL dbt_score-0.19.0-py3-none-any.whl
Size 36.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08c8d77a827d0b7fa9140ca708344db40f822ca38708e64e8171d04e8c83b7fc
BLAKE2b-256 checksum
How to use checksums
392e8356f525dfd2c1874be563c5022d122348bb36112aae1162e18173916ab6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for dbt-score 0.19.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page