Module 0 · Concepts & The Method

​

What an ontology is here

​

The principles

• Just files. Business definitions, SQL templates, notes, and operating rules live in one versioned file tree. Portable, diff-able, and yours.
• Locality of behavior. You should understand a metric by reading its file and the few it imports — no black-box compiler. .tql renders inspectable native warehouse SQL.
• Governed by default. Semantic changes are proposed → diffed → reviewed → approved → audited, like software.
• Ana does the heavy lifting. She inspects a .tql file, renders SQL from parameters, and executes it — preferring a governed surface over ad-hoc SQL.
• Discovery first. Build from what’s actually there — start by reading the schema and the documents, not from assumptions.

​

Why this approach wins — field lessons

• Their prior work isn’t wasted — it’s a corpus. dbt models, LookML, Omni configs, Power BI datasets, wikis, spreadsheets — none needs to be reformatted or migrated. Drop it in; Ana reads it and starts from a warm place.
• You’re not writing the ontology — Ana is. She makes most of the structural decisions and physically writes the content. You are the captain and reviewer, keeping her directionally correct. Ana is self-referential: she knows what context an agent needs.
• You’re not building blind — you need a North Star. Establish what the ontology is for before anything goes in the repo. BI parity, analyst self-serve, and operational/embedded queries each want a different shape (governance, strictness, flexibility). An ontology without a North Star is expensive guesswork.

​

The research behind it

• Invert the lifecycle: the agent reads prior knowledge → explores only the frontier → answers → commits new definitions back to a version-controlled, executable semantic layer. Discovery is amortized across tasks and agents, not re-incurred per request.
• Measured results: ≥30% fewer tokens (up to ~50% on complex multi-join queries), ~41% fewer SQL probe-turns, per-query cost falls toward a “novelty floor” as the layer accretes knowledge (most of a warehouse learned in ~35 queries), and switching backends (DuckDB→Postgres) required no change — definitions are dialect-independent.
• Trust by construction: every write-back is a git commit with an author + diff; definitions are executable, so they’re validated mechanically (recompile + run) rather than re-read as prose; high-stakes paths route to human review (CODEOWNERS-style).

​

The repository shape

ontology/
  schema.tql            central table backings (rename once, everywhere follows)
  relations/            per-source modules: table source + reusable expressions + metric keys
  dimensions/           grouping expressions, each with the join it needs
  filters/              reusable filter predicates
  queries/              public query surfaces (expose metrics / dimensions / filters)
  notes/                business rationale + decisions, colocated with the code

​

Where each input lands

​

How you know it’s right

• Every query renders inspectable SQL — you can read exactly what ran.
• Golden-query tests pin a known-correct value and alert on drift.
• Flexibility ↔ accuracy is a per-metric dial: exact where it must be, flexible where exploration matters.

​

The expert shortcut — seed from what you already know

Here are assets that already encode how our data joins and what our metrics mean: [attach or paste: ERD, canonical SQL queries, dbt models, join documentation]. Seed the ontology from these directly - sources, join paths, and metric definitions - instead of rediscovering them by exploration. Show me everything you extracted as a reviewable change, and flag anything ambiguous or conflicting rather than guessing.

​

✅ Checkpoint

• You can explain “just files” and why git-backed matters
• You know the six folders of the repo shape and what goes in each
• You know where a metrics doc vs. a call transcript lands in the model
• You can pitch a skeptic: prior work = corpus, Ana writes it, North Star first, never a form
• You can cite the research: the “amnesia tax” and the ≥30% token reduction from a malleable layer