What is a semantic layer (and why agents need one)

Agents are hungry for data. They plan, call tools, and write answers that look authoritative. Without a shared meaning layer, each agent invents its own path to a number. Revenue becomes three different sums. Active users become four different filters. The semantic layer exists to stop that drift.

Meaning before SQL

A semantic layer sits between raw warehouse tables and the consumers that need answers. Consumers include dashboards, notebooks, APIs, and now agents. The layer holds named metrics, dimensions, entities, and relationships. When something asks for monthly recurring revenue, it does not invent a join or a date filter. It asks for the metric by name.

That distinction matters for agents. Language models are excellent at producing plausible SQL. They are poor at knowing which SQL matches the definition finance signed off on last quarter. A semantic layer turns “what is MRR?” into a contract: a registered metric with a description, grain, and aggregation rules.

Why agents need it more than dashboards

Dashboards are built by people who already know the warehouse. Agents arrive with a goal and a tool list. They will try every path that might work. If the only path is free-form SQL against production tables, you get inconsistent answers and risky joins.

Agents also chain steps. One tool call feeds the next. If the first call returns an informal number, the rest of the plan inherits that error. A semantic layer gives agents a catalog they can list, metrics they can describe, and a single query interface they can call without rewriting business logic each time.

What datahashi exposes

datahashi is a thin semantic layer for agent workloads. It does not pretend to replace your warehouse. It ships rollups for hot questions. It does not promise a p99 latency target. It focuses on governed meaning and a stable request shape.

Through MCP, agents can use six tools. list_catalog shows what metrics and entities exist. describe_metric returns the contract for one or more metrics: definition, grain, and related dimensions. run_semantic_query asks for that metric with filters and time range in a structured request. drill_down, refine_semantic_query, and list_dimension_values cover the rest. Metering exists so you can see what was called and how often.

The same number, every consumer

The point is not clever caching. The point is that a human analyst, a dashboard, and an agent all resolve “active customers” to the same definition. When the definition changes, it changes once. Agents do not need a new prompt. They need an updated catalog entry.

That is the same-number test in practice. If two agents and one BI tool can disagree on a headline KPI, you do not have a semantic layer. You have a suggestion box for SQL.

Start with contracts, not coverage

You do not need every table modeled on day one. Pick the metrics agents already ask for. Register them. Make them discoverable. Keep the layer thin. Let the warehouse stay the system of record for storage and compute.

Agents will keep writing fluent answers. Your job is to make sure the numbers underneath those answers are the ones your business already agreed on. A semantic layer is how you do that without teaching every agent your schema by hand.