Skip to main content

metricview-lint

Catch mistakes in Databricks Unity Catalog metric view definitions before you deploy them, in your editor, in CI, or while a coding agent like Claude Code writes them.

$ metricview-lint examples/invalid
examples/invalid/common-mistakes.yaml:8: error MV406 join 'customer' 'on' compares customer_id = customer_id; unqualified columns resolve to the joined table, so this is always true. Write source.customer_id = customer.customer_id or use 'using: [customer_id]'
examples/invalid/common-mistakes.yaml:20: error MV302 measure 'margin' has no aggregate function (SUM, COUNT, AVG, MEASURE, ...); a non-aggregated expression belongs in 'fields'.
examples/invalid/common-mistakes.yaml:22: error MV305 MEASURE(orders) references a measure defined later; move 'orders' above 'aov'
examples/invalid/common-mistakes.yaml:31: error MV502 measure 'revenue_7d': invalid range 'last 7 days'; expected current, cumulative, all, or 'trailing|leading <n> [day|month|year] [inclusive|exclusive]'
...

Metric views are defined in YAML inside CREATE VIEW ... WITH METRICS LANGUAGE YAML AS $$ ... $$. Today the only way to find a mistake is to run the statement against a warehouse and read the error. Some mistakes don't error at all: an unqualified on: id = id join condition is always true. metricview-lint checks the definition offline, in milliseconds, with no Databricks connection or credentials.

Install

uvx metricview-lint path/to/metric_views     # run without installing
pip install metricview-lint                   # or install it

It reads .yaml / .yml metric view bodies and .sql files containing CREATE VIEW ... WITH METRICS or ALTER VIEW ... AS $$. Line numbers always point into the original file. YAML files without a top-level source, fields or measures key are skipped, so you can point it at a whole repo.

metricview-lint [PATH ...] [--format text|json|github] [--disable MV201,MV303]
                [--warnings-as-errors] [--all-yaml] [--list-rules] [--mcp]

It exits with 1 if there are errors (or warnings, with --warnings-as-errors), and 0 otherwise.

Use it from Claude Code (MCP)

metricview-lint ships an MCP server. With it, an agent validates every metric view it writes and fixes the errors before showing you the result.

claude mcp add metricview-lint -- uvx --from 'metricview-lint[mcp]' metricview-lint --mcp

Tools exposed:

  • lint_metric_view(definition) takes YAML or a full CREATE VIEW ... WITH METRICS statement and returns the diagnostics.
  • lint_metric_view_file(path) lints a file on disk.
  • list_rules() returns every rule with its code, severity and summary.

The same command works in any MCP client (Claude Desktop, Cursor, ...).

pre-commit

repos:
  - repo: https://github.com/1yangsh/metricview-lint
    rev: v0.1.0
    hooks:
      - id: metricview-lint

GitHub Actions

This annotates the pull request diff at the offending lines.

- uses: actions/checkout@v4
- uses: 1yangsh/metricview-lint@v0.1.0
  with:
    paths: metric_views/
    args: --warnings-as-errors

Rules

Errors are things Databricks rejects, or that silently compute the wrong number. Warnings are likely mistakes that are valid in some setups. Run metricview-lint --list-rules for the live list, and disable any rule with --disable.

Code Severity Checks
MV000 error the YAML parses (with hints for backticks, : in expressions, unquoted *)
MV001 error no duplicate keys (YAML silently keeps the last one)
MV100 error the document must be a YAML mapping
MV101 error version is required
MV102 error version must be a supported spec version
MV103 error source is required
MV104 error at least one of fields or measures is required
MV105 error fields and dimensions are synonyms; use only one
MV106 warning unknown key (likely a typo)
MV107 error value has the wrong type
MV108 error feature requires spec version 1.1
MV109 error window is only allowed on measures
MV201 warning field/measure has no name (derived names need DBR 19+)
MV202 error name must not be empty
MV203 error names must be unique across fields and measures (case-insensitive)
MV204 error wildcard expressions can't have a name or metadata
MV205 error display_name/synonyms length limits
MV301 error fields and measures need an expr
MV302 error measure expr must use an aggregate function
MV303 warning field expr should not aggregate
MV304 error window functions (OVER) are not allowed; use a window measure
MV305 error MEASURE() must reference an earlier measure
MV306 warning aggregating a measure by name; use MEASURE(name)
MV307 error a window measure can't reference another window measure
MV308 error fields can't reference columns of a one_to_many join
MV401 error joins need name and source
MV402 error joins need exactly one of on or using
MV403 error join names must be unique among siblings
MV404 error cardinality must be many_to_one or one_to_many
MV405 error a join subtree can't mix cardinalities
MV406 error on compares an unqualified column with itself
MV501 error window must be a list of specs with order and range
MV502 error window range syntax
MV503 error window order must name a field defined in this view
MV504 error window semiadditive must be first or last
MV505 error window offset syntax
MV506 error window size parameters must be declared and integral
MV601 error format spec is invalid
MV701 error materialization mode and materialized_views are required
MV702 error materialized view entries need a valid name and type
MV703 error materialized views must reference existing fields and measures
MV704 error materialization is incompatible with this definition
MV801 error parameters need name and data_type; defaults come last

The rules follow the metric view YAML reference for spec versions 0.1 and 1.1, including joins (many_to_one / one_to_many, snowflake nesting), window measures, semantic metadata (display_name, format, synonyms), parameters and materialization. Every example in the Databricks docs lints clean, apart from intentional fragments.

What it can't check

metricview-lint works offline, so it can't check anything that needs the catalog:

  • whether tables and columns exist
  • column types (e.g. that a window order is a date)
  • row-level security that blocks materialization

Treat it as a fast first gate, and keep CREATE VIEW on a dev warehouse as the final check.

Development

uv sync --all-extras
uv run pytest && uv run ruff check . && uv run pyright

New rules live in src/metricview_lint/rules/. Each rule is a generator registered with @rule(code, severity, summary) that yields (message, path). Add a failing case to tests/test_rules.py first.

License

Apache-2.0. This is an independent project, not affiliated with or endorsed by Databricks.

Metadata

Release files for metricview-lint 0.1.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 metricview-lint 0.1.0
File Size Uploaded Provenance Actions
metricview_lint-0.1.0.tar.gz 27.2 kB Without provenance Details for metricview_lint-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for metricview-lint 0.1.0
File Interpreter ABI Platform Actions
metricview_lint-0.1.0-py3-none-any.whl Python 3 none any Details for metricview_lint-0.1.0-py3-none-any.whl

Total release size: 60.8 kB

Release files / metricview_lint-0.1.0.tar.gz

Download URL metricview_lint-0.1.0.tar.gz
Size 27.2 kB
Tags Source
SHA-256 checksum
How to use checksums
66719648a01cc825d041d5563a935c93dca4f741c6ad6102055bede5875b1bc7
BLAKE2b-256 checksum
How to use checksums
12b383a64d68a4319989b0f3ee70b3f2d8aa4c814176018e1719256dbeceba19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / metricview_lint-0.1.0-py3-none-any.whl

Download URL metricview_lint-0.1.0-py3-none-any.whl
Size 33.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
816e5d5f3982fb8d11896d17666d3e522ff20efbd85019f0d8e3896d6c469e80
BLAKE2b-256 checksum
How to use checksums
d695aca4f2e43da28494507cb8e419a5d65724e8a729805b5b65e94ba5d97a0c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for metricview-lint 0.1.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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

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