Home › Learn › Hard problems by layer › Semantic layer
Hard problems by layer · 9 of 10
Semantic layer: hard problems and anti-patterns
The hard challenges and common anti-patterns of semantic layer in a data platform, with how each is solved and tested. This layer must keep every business definition in one governed place that people, tools and agents all read.
Where we are
Semantic layer
What this layer must achieve. Keep every business definition in one governed place that people, tools and agents all read.
Handled by: semantic layer generators, metadata store.
The hard part
5 challenges, and how they are solved
Every example comes from the tyre world, a synthetic tyre company whose fourteen simulated days carry planted problems with known right answers, so each fix is tested, not just described.
| Challenge | What goes wrong | Tyre-world example | How we solve it | Verdict | Status |
|---|---|---|---|---|---|
| Definitions nobody agreed SEM-01 | Two teams certify different OTIF formulas. | Partial deliveries counted or not. | The tool versions, certifies and tests definitions and flags two that disagree; the definition itself is a business decision. assurance rules SERV-04; decisions ADR-022 Metrics are certified before conversation interfaces and agents use them. | people decide | building |
| Definitions that change silently SEM-02 | Last year's number changes and nobody knows why. | OTIF definition changed in January. | Versioned definitions with a restatement note. assurance rules SERV-04. | solved | designed |
| Words people actually use SEM-03 | Questions in plain language miss because people say sell-through, sell-out or sales. | Synonyms for OTIF. | Synonyms and descriptions declared with each metric; new synonyms suggested from questions asked. assurance rules SERV-06. Shift-left checks that guard it: SL-SEM-07. | assisted | building |
| Security inside metrics SEM-04 | A regional manager sees other regions' totals through an aggregate. | Region-level sales. | Row filters declared once and applied in every metric. assurance rules SEC-02. Shift-left checks that guard it: SL-SEC-01, SL-SEC-02, SL-SEC-03, SL-SEC-04, SL-SEC-05, SL-SEC-08 and 1 more. | solved | building |
| Provisional numbers that look final SEM-05 | A partial window is read as final. | Sales while one dealer's file is missing. | The complete flag from gold is carried into every metric and shown. assurance rules SERV-02. | solved | building |
What not to do
Common anti-patterns
An anti-pattern is a habit that looks reasonable and keeps causing the same damage. These are the ones seen most often at this layer.
| Anti-pattern | Why it hurts | Do this instead |
|---|---|---|
| Business logic in BI tools or views | The same metric gets computed differently in each dashboard, and nobody can test it. | Put calculations in gold build() or in the semantic layer's metric definitions. |
| Pointing a conversational query tool at raw silver tables | The tool then guesses joins and meanings and gives plausible but wrong answers. | Point it at metric definitions and described gold tables. |
FAQ
Questions people ask
What are the hardest problems in the semantic layer layer?
Definitions nobody agreed; Definitions that change silently; Words people actually use; Security inside metrics; Provisional numbers that look final.
What is the most common mistake at semantic layer?
Business logic in BI tools or views. Put calculations in gold build() or in the semantic layer's metric definitions.
Next
Where to go next
Next: Semantic to UI
↑ All layers · All 69 challenges, filterable · Shift left: fail fast on data code · Medallion architecture