metricview-lint
Offline linter + MCP server for Databricks Unity Catalog metric view YAML
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/1yangsh--metricview-lint)HTML
<a href="/listings/1yangsh--metricview-lint"><img src="/api/listings/1yangsh--metricview-lint/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 155 lines
- # metricview-lint
- <!-- mcp-name: io.github.1yangsh/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.
- ```text
- $ 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
- ```bash
- 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.
- ```text
- 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.
- ```bash
- 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](https://www.schemastore.org) and give you key completion, hover docs and type checks while you type. For any other file name, add this first line:
- ```yaml
- # 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
- ```yaml
- 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.
- ```yaml
- - 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](https://docs.databricks.com/aws/en/uc-semantics/metric-views/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
- ```bash
- 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.