← Back to Articles
Series · 6 parts

Semantic Layer Pills

A series for people learning semantic layers and analytics engineering, built from a real Postgres database, a real dbt project, and a real text-to-SQL agent. Each pill adds one piece of context, no context, descriptions, business logic, routing, access control, and checks whether it actually stops the model from getting things wrong.

Series map

flowchart LR
    P0["0 · Zero Context"] --> P1["1 · Column Descriptions"] --> P2["2 · Business Logic & Grain"] --> P3["3 · Routing"] --> P4["4 · Access Control"]
    P4 -.->|lessons learned| P5["5 · 9 Real Errors"]
  1. 00

    Semantic Layer Pill 0: What Happens When You Give an LLM a Database and Zero Context

    A hands-on guide: clone a real Postgres + dbt project, run an LLM against it with zero schema context, and watch it hallucinate. Step by step, on your own machine.

    Semantic LayerLLMAnalytics EngineeringSQL
  2. 01

    Semantic Layer Pill 1: Can Column Descriptions Alone Stop an LLM From Hallucinating SQL?

    Step-by-step: give the same LLM the full dbt semantic layer with one-line column descriptions, and see whether documentation alone fixes what Pill 0 broke.

    Semantic LayerdbtLLMAnalytics Engineering
  3. 02

    Semantic Layer Pill 2: When One-Line Descriptions Aren't Enough

    Hands-on: swap one-line descriptions for deep doc blocks, deliberately break a dbt contract to watch it fail loudly, and reproduce a real grain bug that richer documentation didn't catch.

    Semantic LayerdbtData GovernanceAnalytics Engineering
  4. 03

    Semantic Layer Pill 3: Routing — Giving the Model Only What the Question Needs

    Read a real routing config, run it against a live agent, then deliberately revert one function to its old, buggy version and watch a real misrouting bug come back on your own machine.

    Semantic LayerAnalytics EngineeringLLMSQL
  5. 04

    Semantic Layer Pill 4: Locking It Down With Real Access Control

    Prove a Postgres role actually enforces read-only access with your own psql commands, then run six brand-new questions against the fixed agent and try to find the same bugs the original project found.

    Semantic LayerData GovernanceSQLAnalytics Engineering
  6. 05

    Semantic Layer Pill 5: 9 Real Errors You'll Hit Building a Semantic Layer

    A hands-on catalog of nine real bugs from building a dbt semantic layer, with the exact file, line, and a query you can run against your own restored database to see the evidence yourself.

    Semantic LayerdbtAnalytics EngineeringSQL