Grounded in: r/dataengineering, "Semantic layer" (193 upvotes, 126 comments), with direct quotes from OP cyamnihc and commenters financialthrowaw2020, wearz_pantz, and Fun-Estimate4561
A data engineer named cyamnihc asked the question a lot of teams are quietly stuck on right now:
"What exactly is it? Annotated table and field names and definition of every field in a text doc?"
Execs had decided AI enablement's first step is "the semantic layer," and someone had to figure out what that actually means in practice. The harder part of the question, the one that got 126 comments:
"Documenting field and metric definitions which also evolve will take a long time, how is this being done at scale?"
The top reply, at 241 upvotes, cut straight past the tooling question:
"the semantic layer is just metadata and context, yes, and it's useless without good underlying data."
That's true, but it also dodges the actual problem. Metadata sitting in a doc doesn't stay accurate. Someone changes how "Active Users" is calculated, updates the dashboard, and forgets the doc exists. Six months later the doc and the dashboard disagree, and nobody notices until someone builds a report off the doc and gets numbers nobody recognizes.
One commenter, wearz_pantz, described the version of this that actually holds up:
"I used AI to create a semantic layer API that deterministically translates requests for dimensions/metrics into SQL and returns data. That way, any AI seeking metrics can just ask for the metric, without needing to generate SQL."
The distinction matters. A doc describes a metric. An API enforces it, one owner, one definition, one place the calculation lives, and every query for "Active Users" runs through that same logic instead of a fresh SQL guess written by whoever's asking.
The same commenter made the harder point explicit, arguing against "just get everyone writing better docs" as the fix:
"Maintaining good data documentation at scale... requires a tonne of mundane writing. Of all the DE activities it's arguably the one AI is best suited for. Actually creating the semantic model, deciding how they relate, and how to calculate metrics with them is the thing that makes humans valuable in DE, not maintaining documentation."
Writing the definition down isn't the hard part. Deciding it, once, in a place downstream queries can't silently override, is.
A third comment, from Fun-Estimate4561, connected this straight to the reason execs are suddenly asking about it:
"to make AI successful in a business... requires a successful semantic layer on top of your warehouse."
That's the trap teams are walking into right now. They're pointing an LLM at a warehouse full of metrics nobody agreed on, and getting confident, fluent, wrong answers back, because the model has no way to know "Revenue" means something different in two different tables. The AI isn't the problem. It's just fast enough to expose a definition problem that was already there, at a scale a human skimming a dashboard used to be slow enough not to notice.
This is the same failure whether a human or a model asks the question. "How many active users do we have?" gets answered instantly and confidently, twice, two different numbers, both technically computed correctly from two different definitions that never got reconciled. A text doc describing the field doesn't stop that. Only a single place the metric is actually calculated, with an owner who has to sign off before anyone changes it, does. That's not a documentation project. It's an ownership decision most teams have never explicitly made, because until an AI agent started asking, nobody was querying the warehouse fast enough for the disagreement to surface every day.