Where should shared metric definitions live so that a dashboard, a notebook and an API all produce the same number?

Why the alternatives drift

Per-tool configuration means the same logic implemented in as many places as there are tools, maintained by different people, diverging on the first change. Documentation is the same problem with no enforcement at all.

Materialised tables are closer — they centralise the computation — but they fix the grain and the dimensions in advance. A consumer needing a cut that was not pre-aggregated writes their own query, and the definition escapes.

What the semantic layer provides

• One definition, executed by every consumer, so consistency is structural rather than procedural.
• Definitions expressed against a modelled schema, so dimensions and filters compose without the consumer reimplementing joins.
• Governance at the definition, including access rules and deprecation.
• A change surface: altering a metric changes it everywhere, which is the point and also the risk — so metric changes need versioning and notice, exactly like an API.

The trade-offs to state plainly

It is another system to run, and it sits on the query path, so its performance is the consumer's performance. It also constrains analysts, who can no longer write whatever SQL they like against base tables — and if the layer is slower or less expressive than direct access, they will bypass it.

The layer succeeds only if using it is easier than not using it. That is an engineering requirement, not a policy one.