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, ...).

Editor autocompletion (JSON Schema)

Name your files *.metric_view.yaml (or *.metric-view.yaml). VS Code (with the Red Hat YAML extension), JetBrains IDEs and Neovim then pick up the schema from SchemaStore and give you key completion, hover docs and type checks while you type. For any other file name, add this first line:

# yaml-language-server: $schema=https://raw.githubusercontent.com/1yangsh/metricview-lint/main/schemas/databricks-metric-view.json

The schema is lenient on purpose: it helps you write the file, and metricview-lint checks it. metricview-lint --print-schema prints it.

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.1

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.1
File Size Uploaded Provenance Actions
metricview_lint-0.1.1.tar.gz 30.6 kB Without provenance Details for metricview_lint-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 67.9 kB

Release files / metricview_lint-0.1.1.tar.gz

Download URL metricview_lint-0.1.1.tar.gz
Size 30.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0a91a679199bba85d543c0ea1b7a650985e73d7cd3ecfcef06cfd0aa38eed17e
BLAKE2b-256 checksum
How to use checksums
9fbd340afb7bb31f3855996f45b28713efcc8854bb14494fd92bcafa7a5fbde9
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.1-py3-none-any.whl

Download URL metricview_lint-0.1.1-py3-none-any.whl
Size 37.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
809a1a2cfc0e412dbeb278ab7c2f520b1a130ec6bb6d1bdbd8832706c3a0e629
BLAKE2b-256 checksum
How to use checksums
1679294f6532c29fb75c7c46acd217c099cb32a59e728e938f353f27fe26318e
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.1

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.1 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