Metadata-Version: 2.4
Name: metricview-lint
Version: 0.1.0
Summary: Offline linter and MCP server for Databricks Unity Catalog metric view YAML
Keywords: databricks,unity-catalog,metric-views,semantic-layer,linter,mcp,claude-code
Author: Seunghyeon Yang
Author-email: Seunghyeon Yang <61305117+1yangsh@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: pyyaml>=6.0.4
Requires-Dist: mcp>=2,<3 ; extra == 'mcp'
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/1yangsh/metricview-lint
Project-URL: Issues, https://github.com/1yangsh/metricview-lint/issues
Provides-Extra: mcp
Description-Content-Type: text/markdown

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

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