# Query the semantic layer with SQL - Docs

The whole semantic layer is queryable with [SQL](/docs/data-warehouse/query.md) through `system.information_schema` – from the SQL editor in PostHog or the `execute-sql` MCP tool. This is also how agents discover metrics: there's no "list metrics" tool by design, just these tables.

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

## system.information\_schema.metrics

One row per metric in your project:

| Column | Type | What it is |
| --- | --- | --- |
| id | String | The metric's id. |
| name | String | Write-once identifier, e.g. mrr. |
| display_name | Nullable string | Human-friendly label. |
| description | String | What the metric means – the text agents match questions against. |
| unit | Nullable string | e.g. usd, percent. |
| status | String | proposed or approved. |
| is_drifted | Boolean | Whether the definition has drifted from its source insight. Computed at read time. |
| definition | Nullable string | The machine-readable definition, or null for a stub. |
| definition_kind | Nullable string | HogQLQuery, TrendsQuery, MarkdownDefinition, ... |
| owner | Nullable string | Email of the accountable human. |
| confidence | Nullable float | AI author's confidence, 0-1, when AI-authored. |
| reasoning | Nullable string | AI author's reasoning, as review context. |
| source_insight_short_id | Nullable string | The insight the metric was created from, if any. |
| last_run_at | Nullable string | When the metric last ran. |
| created_at | String | When the metric was created. |

Metrics whose definitions reference tables you don't have access to are hidden from your results.

### Find a metric

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'+OR+description+ILIKE+'%25revenue%25')

PostHog AI

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

### List everything canonical

SQL

[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT+name%2C+display_name%2C+unit%2C+owner%0AFROM+system.information_schema.metrics%0AWHERE+status+%3D+'approved'+AND+is_drifted+%3D+false)

PostHog AI

```sql
SELECT name, display_name, unit, owner
FROM system.information_schema.metrics
WHERE status = 'approved' AND is_drifted = false
```

### The review queue

SQL

[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT+name%2C+display_name%2C+confidence%2C+reasoning%0AFROM+system.information_schema.metrics%0AWHERE+status+%3D+'proposed')

PostHog AI

```sql
SELECT name, display_name, confidence, reasoning
FROM system.information_schema.metrics
WHERE status = 'proposed'
```

**Check before you trust**

A result is canonical only when `status = 'approved'` and `is_drifted = false`. Always check both columns before treating a metric – or its output – as the source of truth.

## Certifications in system.information\_schema.tables

Each table row carries its trust mark in the `certification` column (`certified`, `deprecated`, or null):

SQL

[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT+table_name%2C+table_type%2C+description%2C+certification%0AFROM+system.information_schema.tables%0AWHERE+certification+IS+NOT+NULL)

PostHog AI

```sql
SELECT table_name, table_type, description, certification
FROM system.information_schema.tables
WHERE certification IS NOT NULL
```

## Relationships in system.information\_schema.relationships

Relationships lists every joinable path between tables. Rows that came from an accepted catalog proposal carry the reviewed `confidence` and `reasoning`:

SQL

[Run in PostHog](https://us.posthog.com/sql?open_query=SELECT+source_table%2C+source_column%2C+target_table%2C+target_column%2C+confidence%2C+reasoning%0AFROM+system.information_schema.relationships%0AWHERE+confidence+IS+NOT+NULL)

PostHog AI

```sql
SELECT source_table, source_column, target_table, target_column, confidence, reasoning
FROM system.information_schema.relationships
WHERE confidence IS NOT NULL
```

For the rest of the `information_schema` surface – columns, data types, statistics – see the [data warehouse SQL docs](/docs/data-warehouse/query.md).

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better