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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.