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 fullCREATE VIEW ... WITH METRICSstatement 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
orderis 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.