The Semantic Layer, in seven episodes

Seven short films on why pipelines store shape instead of meaning, and what changes when they stop.

1. Episode 1 · dbt
   Why Your Data Pipeline Stores Shape, Not Meaning | Episode 1

   A deep-dive technical discussion on why modern data stacks fail to maintain business definitions. We walk through a two-minute diagnostic experiment you can run on your codebase to expose where critical business rules have drifted across duplicated, unlinked files. We examine why traditional PR templates and external catalogs fail because they lack downstream dependents, and we explore how representing business definitions as first-class, named objects can structurally solve this. Finally, we discuss how configuring dbt's native persist_docs comment conduit physically pushes these governed meanings directly into database column comments to reach your downstream analysts in their native SQL autocomplete.

   Docs for dbt →
2. Episode 2 · dbt
   The Green Build Illusion: Why Successful dbt Tests Hide Broken Dashboards | Episode 2

   Two senior engineers analyze the "green-build illusion"—why local test suites can remain entirely green even when duplicate permitted-value lists have quietly drifted apart. Because dbt treats enums as isolated, independent string arrays, it lacks a native mechanism to compare them against one another. We discuss the severe operational cost of slightly-wrong data (such as a missed return status code) quietly eroding stakeholder trust on executive dashboards. Finally, we map out how to transition from fragmented string arrays to named, structured vocabularies, and share a practical workflow for sorting your vocabularies by reference count to identify high-leverage business terms.

   Docs for dbt →
3. Episode 3 · dbt
   Trapped Metadata: The Data Warehouse Ticket Nobody Files | Episode 3

   We examine an invisible, daily breakdown in data communication: the analyst querying raw warehouse tables late at night. Lacking access to your dbt repository, they are forced to guess what ambiguous database columns signify, propagating silent inaccuracies without ever filing a ticket. We discuss why traditional documentation repositories fail to reach these users, and show how configuring dbt's persist_docs setting turns database column comments into a direct conduit. By pushing governed definitions straight into the physical warehouse comments, you meet external analysts exactly where they work, integrating business definitions directly into their SQL autocomplete.

   Docs for dbt →
4. Episode 4 · dbt
   Why AI Coding Assistants Write Plausible but Inaccurate SQL | Episode 4

   AI coding agents and text-to-SQL systems excel at parsing names and data types, yet they consistently write incorrect queries because they lack access to underlying human intent. We explore the structural difference between SQL computation and semantic logic, analyzing the risks of silent, plausible errors (such as an LLM failing to distinguish between nuanced order return stages). We outline the "fourth option" for LLM integration: providing AI tools with a read-only, human-curated semantic model. Finally, we discuss why writing explicit descriptions of "common mistakes" for your 20 highest-leverage columns yields far better AI-generated SQL than paragraphs of dry documentation.

   Docs for dbt →
5. Episode 5 · dbt
   The Blast Radius of Column Renames: Why We Tolerate Invisible Technical Debt | Episode 5

   Why do development teams routinely avoid simple column renames? We break down the unbounded cost of discovering where a schema change propagates. Traditional model-level dependency graphs map internal lineage but completely miss external consumers (reverse-ETL pipelines, BI tools, direct database queries, and external APIs) and semantic owners. We discuss how tracking the conceptual relationship path of a vocabulary through a governed model transforms an endless manual search into a finite, 20-minute checklist, giving engineers the structural confidence to clean up their codebases.

   Docs for dbt →
6. Episode 6 · dbt
   Meaning is Not File-Shaped: Designing a Reusable Data Ownership Register | Episode 6

   Technical code ownership typically links individuals to physical files, but business definitions frequently span multiple models. This mismatch forces developers to make isolated business decisions they are not qualified to handle. We discuss how to structure a centralized metadata register based on persistent decision forums (which survive individual employee turnover) and explicit review cadences rather than fragile individual assignments. Finally, we analyze a proactive day-one operational strategy: blanket-assigning "wrong" owners to spark corrections and turn a vague cultural issue into a transparent, prioritized backlog of work.

   Docs for dbt →
7. Episode 7 · dbt
   The PR Testing Blindspot: Catching Deleted Constraints in CI Gating | Episode 7

   Modern software development pipelines suffer from a systemic vulnerability: deleted constraints and tests go completely unnoticed in pull requests. Because standard branch-versus-main diffs evaluate only what currently exists, a branch that removes critical tests still passes CI green. We analyze how implementing a "fourth comparison"—evaluating compiled branch projects against a baseline governed model—enforces structural accountability automatically rather than relying on fragile human memory. We close with a practical implementation strategy: triaging and recording deliberate deferrals of existing drift to avoid creating noisy red builds on day one.

   Docs for dbt →

The full playlist is on YouTube.