<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Xiaoyu Zhang on Medium]]></title>
        <description><![CDATA[Stories by Xiaoyu Zhang on Medium]]></description>
        <link>https://medium.com/@xiaoyu.zhang_20482?source=rss-3decb6ec3132------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*7RsP4S94f1BzJutm</url>
            <title>Stories by Xiaoyu Zhang on Medium</title>
            <link>https://medium.com/@xiaoyu.zhang_20482?source=rss-3decb6ec3132------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 15:48:50 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@xiaoyu.zhang_20482/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Semantic Layer as Scaffolding for Your Data Warehouse]]></title>
            <link>https://medium.com/data-systems-internal-ai-personio/semantic-layer-as-scaffolding-for-your-data-warehouse-9b0e70935499?source=rss-3decb6ec3132------2</link>
            <guid isPermaLink="false">https://medium.com/p/9b0e70935499</guid>
            <category><![CDATA[data-warehouse]]></category>
            <category><![CDATA[dbt]]></category>
            <category><![CDATA[semantic-layer]]></category>
            <category><![CDATA[analytics-engineering]]></category>
            <category><![CDATA[metricflow]]></category>
            <dc:creator><![CDATA[Xiaoyu Zhang]]></dc:creator>
            <pubDate>Fri, 18 Sep 2026 15:30:42 GMT</pubDate>
            <atom:updated>2026-09-18T15:30:42.999Z</atom:updated>
            <content:encoded><![CDATA[<p><em>By </em><a href="https://medium.com/u/3decb6ec3132"><em>Xiaoyu Zhang</em></a><em>, with </em><a href="https://medium.com/u/a88f8c88ed77"><em>Manuel Gruber</em></a><em>, </em><a href="https://medium.com/u/63bf1cbfb85f"><em>Yuhao Gao</em></a><em>, </em><a href="https://medium.com/u/d081bbe0070e"><em>Julio Ferrer</em></a><em>, and many others on our team, who built what’s described here</em></p><p>Semantic layer has been the hot buzzword of the last couple years in data circles, this round, because of AI. It’s sold like the magic key that unlocks your data for AI, and somehow, by the name alone, people get the impression that it’s just a stale and additional layer sitting next to your data models. Build it once, and you’re free in the LLM ocean.</p><p>Both the assumption and the approach are a bit off. Whether semantic layer is really <em>the</em> key to AI is a bigger debate, one we’ll save for later, when we can walk through our own experience building a data agent. It played a real role there, just not the only one.</p><p>What we want to get into here is something else: even knowing semantic layer isn’t the ultimate key, we still think it’s worth doing, and the reason cuts against the exact belief that gets people building one in the first place, that you build it once and you’re free. The truth is more complex than that.</p><p>There are usually two instincts once teams realise that. Tear it down and build something new and compliant from scratch. Or bolt on a new layer on top that makes it look right from the outside. We tried both. Neither held. What actually worked was scaffolding: not a product you install and walk away from, but something you keep building with, because the warehouse underneath never stops changing either. Here’s how that played out for us.</p><h3>The Three Attempts</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c9PxjdGGQ6zM4H1BuRC6Pg.jpeg" /></figure><p><strong>It started like building a new building, a new schema.</strong> Around 2,000 dbt models in, we carved out reporting_self_service, a clean schema for self-serve data, fewer than 10 models, strictly named, meant to be the well-governed one. That covered about 1% of our models.</p><p>Adoption stayed low. Coverage was too thin, someone would compare a number against an old dashboard, and we’d have to say “yeah, that’s calculated a bit differently over there.” So now we had two sets of truth instead of one. And nobody checked whether a field added or changed elsewhere needed to be adapted in the new schema too. Not because people didn’t care. Because nothing made anyone check. No visibility, no required step, no payoff for the extra five minutes.</p><p>So we rolled it back. Same old schemas, just tagged “self-serve.” Cheap to undo — it was only a handful of models anyway.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vVgVy5bBNMnunvbA01n8Ew.jpeg" /></figure><p><strong>Next we tried the facade, consolidating terms and metrics instead.</strong> This wasn’t just renaming. We put real effort into defining metrics properly: clear descriptions, agreed formulas, the kind of documentation that’s supposed to make a number mean something specific. cnt_customers and num_customers both became count_customers, properly defined this time. Clearer, sure. But this ran straight into a problem no tool can fix by itself: a customer isn&#39;t one thing. It comes from a CRM system, a billing system, the product itself. So the definition had to grow: count_customers_crm, count_customers_product, each with its own careful write-up.</p><p>Then is_active_customer showed up, and active wasn&#39;t one thing either. Active by login? By subscription status? By usage in the last 30 days? Depends which system you ask. The definitions needed to grow again. And again.</p><p>We came to realise that it didn’t matter how carefully we defined each one. We were still working on top of the same models, the same structure, the same underlying ambiguity. Just describing it more precisely instead of resolving it. “Active” has more than one true answer depending on where you look, and no definition, however well-written, changes that if the models underneath still disagree.</p><p>We only found out how badly this mattered later, once we started asking an LLM to interpret these definitions directly. The same question could get different answers on different days. Nothing had changed, not the model, not the data, just the interpretation. It’s a general problem, and one we still haven’t fully escaped: LLMs don’t guarantee the same answer twice. What a semantic layer actually gives you is a deterministic layer in between, something fixed and version-controlled that the LLM reads from, so the uncertainty gets pushed further out instead of sitting at the center of every answer. That’s part of the data agent story we mentioned earlier, for another time.</p><p>What mattered here was simpler: we were doing careful, honest work. Every time we thought we’d nailed it down, it had already taken a new shape.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7PZ25DDZcI6SHNOaBnzDRg.jpeg" /></figure><p><strong>What actually closed the gap wasn’t a new space or a better definition, it was using semantic layer as scaffolding.</strong> We moved to dbt Metricflow. What mattered wasn’t the tool alone, it was what it gave us. It doesn’t lock the semantic layer inside the warehouse: the same metric definitions can serve BI tools, custom APIs, and AI interfaces alike, instead of being tied to one ecosystem. And the definitions live as YAML files directly in the same dbt repository as the models they describe, checked by real CLI validation before anything deploys: syntax, reserved keyword conflicts, whether the definitions actually resolve against the warehouse. Changes go through the same git workflow as everything else. Branching, PR review, CI checks, rollback if something’s wrong. What used to blow up as a confusing runtime error now shows up as a clear message before anything ships, and because the metric definitions live in the same repo as the models themselves, changing what a number means goes through the same review as changing the table underneath it. Tracked, reviewed, deployed together, not bolted on as some separate layer everyone forgets exists.</p><p>In practice, that’s meant real coverage, not a side room nobody used. We’ve since built out semantic layer for around 40 of our models, covering most of the final, consumer-facing models behind our key data products: facts, dimensions, reporting models like rpt_companies_360_daily and fct_tenant_product_activation. Roughly 900 metrics, 500 dimensions, 400 measures, over 40 entities, and growing. This isn&#39;t a finished count. We&#39;re still rolling out more coverage, model by model, in order of impact, not all at once.</p><p>Defining entities this way, where a customer links to an account and an account links to a contract, is, in a smaller and less formal way, the same kind of work a full ontology project does. We didn’t set out to build one. It came along as a byproduct of getting the metrics right, not as its own initiative. Worth naming, because it’s part of why this held up better than the last two attempts: we weren’t just describing relationships in a definition somewhere, we were encoding them into the models themselves.</p><p>The tool switch wasn’t just a preference, by the way. A facade sits on top of, or next to, the thing it’s dressing up: a translated spec, one step removed from what it actually describes. Scaffolding has to be load-bearing. Attached to what it’s guiding, reviewed and shipped through the exact same process as the thing itself. That’s a structural difference, not just a nicer feature list.</p><p><em>That question — how much to refactor, how much to build new — is where the real renovation starts.</em></p><h3>Why the Renovation Always Comes Late</h3><p>This isn’t really a story about our warehouse. It’s a trap waiting for every data team, regardless of stage.</p><p>Early on, complexity hasn’t surfaced yet: few models, few domains, a handful of people who agree on what “revenue” means because they built it themselves. A semantic layer at this stage looks premature. No visible conflict for it to resolve, so it reads as overhead, and overhead is the first thing to fall out of maintenance. It gets stood up, half-used, and slowly abandoned.</p><p>The complexity doesn’t stay away. More domains, more people, more definitions of the same concept drifting apart quietly, unnoticed, because nothing forces anyone to compare notes. By the time the cost of <em>not</em> having a semantic layer becomes visible, two dashboards disagreeing in front of a stakeholder, an agent giving three answers to the same question, you’re no longer building on a clean slate. You’re refactoring. The conflict isn’t a surface issue anymore. It’s built into the foundation.</p><p>That’s the trap: early, it looks unnecessary; late, you’ve already inherited the mess it was meant to prevent. If the goal is a data warehouse that scales with your team, serves more than a handful of people, and holds up for years, the renovation comes with that ambition. Earlier or later is the only real choice.</p><p>For us, “later” had a specific shape. Self-serve demand was already growing: more people wanting answers directly, fewer willing to wait on a request queue. Then AI accelerated it: we needed a data agent, and the whole point was making our data products genuinely LLM-ready, not just human-readable with an AI layer bolted on top. By the time that need arrived, we’d already tried the two shortcuts, a new space, a better definition, and knew neither would scale. The data agent didn’t create the problem. It made deferring it impossible.</p><h3>Scaffold-Guided Renovation</h3><p>It’s tempting to describe this as two phases: build the scaffolding, then do the renovation. That’s not how it actually went. It happened at the same time, in a loop, over and over: build a piece of the scaffolding, try to define a metric with it, hit a conflict, go get the room full of people who disagree, align, come back, refactor, validate, and sometimes hit a new conflict on the very next pass.</p><p>Scaffolding isn’t just standing something up: it’s making sure it holds before you trust it. So we built a way to check, before anything shipped. The first thing we learned was where AI actually helps and where it doesn’t. It’s fast at generating syntax and boilerplate. It’s no help at all with the actual problem: definition conflicts, lack of business agreement, people defaulting to gut feeling over ground truth. Generation was never the hard part. Trust was.</p><p>That’s why building a semantic model became a conversation between the person defining the metric and the tool doing the technical setup, not a config file written from scratch: describe the business object, the metrics that matter, the questions people will actually ask, and an AI-assisted workflow builds the underlying definition, flagging naming conflicts against every existing model before anything is finalised. That alone caught a class of problem the old approach never could: two metric definers, in two different domains, defining the same term slightly differently without ever knowing the other one existed.</p><p>Then it goes through validation: automated checks that confirm the model is syntactically correct, that the logic behind every metric and join actually holds, and that nothing’s missing a description or a synonym someone will need later. That layer catches broken structure. It doesn’t catch broken meaning. And this is usually where the loop kicks in for real: validation surfaces a naming conflict, or a definition that doesn’t match what another domain already has, and that sends you back to the room, not forward to shipping.</p><p>For the meaning check, we run a local version of our data agent against the unpublished change, and ask it a plain-English question the way a real stakeholder would: “what was our churn rate last quarter,” “how many active customers do we have in a given region.” This isn’t the same risk as asking an LLM to interpret raw ambiguity. The definition it’s querying is already fixed and version-controlled by this point. What we’re testing is narrower: does the agent route the question to the right, already-agreed metric. A person still reviews the answer before anything ships. If it reflects what you intended, you ship it. If it doesn’t, you’ve caught it before anyone else sees a wrong number.</p><p>The other trigger for the loop shows up later, mid-refactor. You’re partway through making an existing model comply with the scaffolding, and a downstream consumer realises just how big the blast radius of a definition change actually is. A dashboard nobody flagged, a report that assumed the old logic. That’s not a bug in the process. That’s the process working: the refactor itself is what makes the real scope of a disagreement visible, and it sends you back to revisit a term everyone thought was already settled.</p><p>None of this happens without a room full of people agreeing on what things actually mean, again and again. That part isn’t usually a turf fight over who owns a metric. It’s a visibility problem. Analysts tend to be deeply domain-specific: they know their own area’s data cold, but rarely have a clear view of how the same term is defined and used two domains over. The analytics engineering team is often the only party with the code-level visibility to notice when two domains have quietly built two different answers to the same question.</p><p>Ownership shifted accordingly. It no longer belongs only to the team that builds the plumbing. The final call on what a metric means now sits with the analysts closest to the business, the people who actually get asked “why does this number look different.” Analytics engineering keeps a different kind of authority: not veto over the definition, but responsibility for flagging when it conflicts with something else already in use elsewhere. Neither side owns the whole thing alone. One owns the meaning, the other owns whether that meaning holds together across the warehouse.</p><p>None of that alignment sticks on its own, which is the whole point of scaffolding: hold the agreement in place, version-controlled instead of tribal knowledge, reviewable instead of a Slack thread nobody can find six months later. People still have to keep showing up to maintain it, and every so often, go back through the loop again.</p><h3>The Building Is Never Finished, Neither Is the Scaffolding</h3><p>Semantic layer is 20% modeling, 80% people and process. It’s not a facade, it’s not a new building — it’s scaffolding. The scaffolding is the smaller, visible part; the renovation it guides is the real, ongoing work.</p><p>Our semantic layer doesn’t stay contained to the warehouse, either. Today it shows up in two very different places: our data agent “Panda”, and our visualisation tool Hex, where analysts query the governed metrics directly instead of writing SQL against raw tables. Same scaffolding, two different rooms depending on it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ef3IY88_ahcBXXTzJiQ7nA.png" /><figcaption>Where the semantic layer shows up in our stack</figcaption></figure><p>If you’re about to start this yourself: don’t mistake the scaffolding for the finished building. The tooling is the easy 20%. The other 80% isn’t a mystery, either. It’s a set of partnerships. One side provides the technical solution: the platform, the process, the cross-domain review. Another consolidates business context from every angle that has a stake in the definition. A third adopts the result, builds a common understanding around it, and feeds back what’s missing or wrong, which is what sends the definition back for re-consolidation. No one of these owns the outcome alone.</p><p>There’s no point where you take the scaffolding down. New domains show up, definitions drift, someone builds a dashboard nobody reviewed, and the scaffolding stays up because that was never the job in the first place. It becomes the backbone of how you construct a data warehouse at all: design with it in mind, develop against it, implement, revisit, refactor, retire. Every stage leans on the same backbone, not a new one each time.</p><p>Regardless of whether semantic layer is the ultimate or only key to AI, still debatable, it built us a way toward it. Not as a bridge, something you cross once and leave behind, but as the backbone itself: the reason the warehouse underneath doesn’t just sit there frozen for a moment, but stays scalable and trustworthy, alongside whatever comes next.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9b0e70935499" width="1" height="1" alt=""><hr><p><a href="https://medium.com/data-systems-internal-ai-personio/semantic-layer-as-scaffolding-for-your-data-warehouse-9b0e70935499">Semantic Layer as Scaffolding for Your Data Warehouse</a> was originally published in <a href="https://medium.com/data-systems-internal-ai-personio">Data • Systems • Internal AI @ Personio</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>