# Certifications and relationships - Docs

[Metrics](/docs/semantic-layer/metrics.md) govern your *answers*. Certifications and relationships govern the *tables the answers come from*: which sources to trust, which to avoid, and how tables join – so agents stop guessing.

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

## Table certifications

A certification is a human-vouched trust mark on a warehouse table or view:

| Status | Meaning |
| --- | --- |
| proposed | An agent (or human) suggested a trust mark; not yet vouched. |
| certified | Prefer this source. A human has vouched for it. |
| deprecated | Avoid this source. A human has warned against it. |

The classic case: your warehouse has both a synced `stripe_charges` table and a hand-rolled `payments_backup` someone loaded last year. Certify `stripe_charges` with a note like "canonical payments source, synced daily" and deprecate `payments_backup` with "superseded by stripe\_charges, stale since March". The notes matter – agents read them when choosing between sources.

The flow mirrors the rest of the semantic layer: anyone proposes with [`data-catalog-certification-propose`](/docs/semantic-layer/mcp-tools.md#certification-tools) (targets can be addressed by id or by name – an ambiguous name returns candidates to pick from), and a human resolves it with `data-catalog-certification-certify` or `data-catalog-certification-deprecate`, both of which require typing "confirm". Revoking a certification deletes it outright, with the change activity-logged.

Certifications surface wherever schemas do: `system.information_schema.tables` rows carry each table's trust mark in the `certification` column, so anything exploring your schema sees them inline:

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+table_name+IN+%28'stripe_charges'%2C+'payments_backup'%29)

PostHog AI

```sql
SELECT table_name, table_type, description, certification
FROM system.information_schema.tables
WHERE table_name IN ('stripe_charges', 'payments_backup')
```

## Relationship proposals

A relationship proposal is a reviewed join fact between two warehouse tables. Instead of every session rediscovering that `orders.customer_id` matches `stripe_customers.id`, an agent proposes the join once – with evidence – and a human accepts it.

A proposal records the two tables, the join keys, a confidence score, reasoning, and sampling evidence: the agent shows its work, like "98% of `orders.customer_id` values match `stripe_customers.id` in a sample". Proposals are deduped regardless of direction, so `orders → stripe_customers` and `stripe_customers → orders` count as the same pair.

| Status | Meaning |
| --- | --- |
| proposed | Suggested with evidence; awaiting review. |
| accepted | Promoted to a real [data warehouse join](/docs/data-warehouse/join.md), after re-validating and probing the keys. |
| rejected | Vetoed. Permanent – the pair is never re-proposed. |

Acceptance and rejection both go through a human with a typed "confirm" ([`data-catalog-relationship-accept`](/docs/semantic-layer/mcp-tools.md#relationship-tools) and `data-catalog-relationship-reject`).

**Rejection is permanent**

Rejecting a proposal persists forever and suppresses the pair from ever being re-proposed – that's what stops agents from suggesting a join you've already vetoed, but it also means there's no undo. Be sure before you confirm a rejection.

Accepted joins become real lazy joins and surface in `system.information_schema.relationships`, carrying the proposal's 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
```

## How agents use trust marks

When the semantic layer is enabled, agents exploring your schema:

-   **Prefer certified tables** and mention when they're using one
-   **Avoid deprecated tables**, citing the deprecation note if they must touch one
-   **Join along accepted relationships** instead of inferring keys from column names

The effect compounds: each certification and accepted join is a decision made once, by a human, that every future session inherits.

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better