Skip to main content
Glama

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.

Related MCP server: deepbom

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Static audit of Kubernetes manifests via MCP, powered by kube-linter. Returns structured reports with severity, check ID, category, message, and remediation hints.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to evaluate text or local files for LLM-output quality issues, returning 0-100 scores, grades, and precise line/column findings. It also lets clients list all available lint rules and severities.
      MIT