# Semantic layer - Docs

Ask three AI tools "what's our MRR?" and you get three different queries and three different numbers. Not because the tools are bad, but because what "MRR" means at your company lives in people's heads. Every agent session reinvents the definition from scratch, and every reinvention is slightly different.

The semantic layer fixes this. It's a per-project catalog of governed definitions that every agent – and every human – reads from the same place. Define MRR once, approve it once, and every session from then on returns the same number.

The guiding principle: **AI generates, a human owns.** Agents can propose metrics, trust marks, and joins all day. Only a human can approve them, and approval is what makes them canonical.

One naming note: the semantic layer is powered by PostHog's data catalog, so you'll see `data-catalog` in MCP tool names (like `data-catalog-metric-run`) and API scopes (`data_catalog`, `data_catalog_approval`).

**The semantic layer is in alpha**

The semantic layer is in alpha, enabled per organization for a small group of customers. There's no dedicated UI yet – you work with it through MCP tools and SQL. Tool names and behavior may change between releases. Found a bug, or want access? [Contact support](https://app.posthog.com/home#supportModal) and mention the semantic layer alpha.

## What's in the semantic layer

The catalog holds three kinds of governed facts:

### Metrics

A [metric](/docs/semantic-layer/metrics.md) is a canonical business measure: a write-once name like `mrr`, a description, a unit, an owner, and a definition that's either an executable query or a set of calculation steps. Metrics move through a `proposed` → `approved` lifecycle, and PostHog detects when an approved definition drifts from the insight it was created from.

### Table certifications

A [certification](/docs/semantic-layer/certifications-and-relationships.md) is a human-vouched trust mark on a warehouse table or view: `certified` means "prefer this source," `deprecated` means "avoid it." Agents exploring your schema see these marks and pick sources accordingly.

### Relationships

A [relationship](/docs/semantic-layer/certifications-and-relationships.md#relationship-proposals) is a reviewed join fact between two warehouse tables, proposed with evidence (match rates, sample values) and, once accepted, promoted to a real [data warehouse join](/docs/data-warehouse/join.md). No more agents guessing join keys.

## How you use it

There's no UI during the alpha. You work with the semantic layer through two surfaces:

**From an AI agent (the main surface).** Connect the [PostHog MCP server](/docs/model-context-protocol.md) to Claude Code, Cursor, Claude Desktop, or any other MCP client. When the semantic layer is enabled, agents route metric questions through the catalog first: ask `What was our MRR last quarter?` and the agent runs the governed `mrr` metric instead of writing its own SQL. See [MCP tools](/docs/semantic-layer/mcp-tools.md).

**From SQL.** The catalog is queryable from the [SQL editor](/docs/data-warehouse/query.md) or the `execute-sql` MCP tool:

SQL

[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT+name%2C+display_name%2C+description%2C+status%2C+is_drifted%0AFROM+system.information_schema.metrics%0AWHERE+name+ILIKE+'%25mrr%25')

PostHog AI

```sql
SELECT name, display_name, description, status, is_drifted
FROM system.information_schema.metrics
WHERE name ILIKE '%mrr%'
```

See the [SQL reference](/docs/semantic-layer/query.md) for the full schema.

## The trust model in 30 seconds

Everything an agent creates lands as `proposed`. A human promotes it – approving a metric, certifying a table, accepting a join – and every promotion requires literally typing "confirm" in the conversation. Editing an approved metric's definition resets it to `proposed`. If a metric was created from an insight and someone later edits that insight, the metric is flagged as drifted.

The rule agents live by: a result is canonical only when `status = 'approved'` and `is_drifted = false`. Everything else gets labeled noncanonical.

Read more in [governance](/docs/semantic-layer/governance.md).

## Next steps

-   [Get started](/docs/semantic-layer/start-here.md) – catalog your first metric in a 10-minute agent conversation
-   [Metrics](/docs/semantic-layer/metrics.md) – definitions, lifecycle, and drift in depth
-   [MCP tools](/docs/semantic-layer/mcp-tools.md) – the full tool reference and example prompts

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better