Skip to content
Ask Claude Ask ChatGPT View as Markdown

Why semantido? (and how it compares)

semantido is code-native semantic layer authoring: a way to declare what your schema means, next to the SQLAlchemy models that define it, and export that meaning to whatever consumes it. This page is the honest version — what it is for, what it is not, and where it loses.

The problem semantido solves

Agents are everywhere: Claude Code, Cursor, ChatGPT, LangChain pipelines, in-house copilots. None of them know what your data means. Point one at a warehouse and it writes confident, plausible, wrong SQL, because the meaning it needs never got written down anywhere it can read.

The specific things a schema doesn't say are remarkably consistent:

  • bridge tables that fan out and silently double-count
  • amount columns whose sign convention lives in a separate code column
  • three different columns that all look like "the amount"
  • four different columns that all look like "the date"

semantido's answer is narrow on purpose: put that meaning in the model file, and get a deterministic artifact out.

How semantido compares

Raw DDL in the prompt A YAML semantic layer (dbt, Cube) A semantic layer platform (Wren, AtScale) semantido
Describes what columns mean ❌ ✅ ✅ ✅
Cannot drift from the schema ✅ ❌ ❌ ✅
Reviewed in the same PR as the migration ✅ ❌ ❌ ✅
Runs queries / serves results ❌ ✅ ✅ ❌
Ships a UI ❌ ❌ ✅ ❌
Vendor-neutral export n/a partial partial ✅ (OSI)
Works without SQLAlchemy ✅ ✅ ✅ ❌

Distinctions worth being precise about:

  • vs. dumping DDL into the prompt: this is the comparison people assume is close. It isn't. Raw DDL is high-volume, low-signal, and in our benchmark it had negative marginal value — see Correctness.
  • vs. a YAML semantic layer: dbt and Cube define metrics in files that live apart from the schema. That works, and it works across warehouses semantido never sees. The tradeoff is drift: nothing structurally prevents the YAML from describing a column that no longer exists.
  • vs. a semantic layer platform: Wren, AtScale, and friends are systems — they run queries, serve dashboards, hold state. semantido is a library that produces a document. It does not compete with them; it can feed them.

semantido is for you if…

  • Your SQLAlchemy models are the source of truth for the schema you want agents to query.
  • You are building text-to-SQL or RAG over a real, gnarly, production schema.
  • You want semantic definitions that are reviewable and versioned in the repo the engineers already work in.
  • You need to hand a semantic model to something else — a BI tool, a catalog, an agent framework — and don't want to bet on one vendor's format.
  • You are in a regulated environment and need "who changed the definition of notional, when, and in which PR" to have an answer.

Skip semantido if…

  • SQLAlchemy is not your source of truth. If your models are generated from the warehouse, or the tables are owned by a dbt project, or your Python service reads tables it doesn't define, code-native authoring is the wrong shape. Use a warehouse-side layer.
  • You need query execution, caching, or aggregation. semantido never touches your database. It reads mappers, not data.
  • You want a UI. There isn't one, and there isn't going to be one.
  • You need cross-warehouse metric federation. That is a platform problem.

Where to go next