> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getinteract.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic layer

> How Interact turns your warehouse tables into named metrics and dimensions, and the two ways to fill it: Interact models and custom models.

## What is the semantic layer?

The semantic layer describes your warehouse data in business terms: which tables exist, which **dimensions** you can group and filter by (channel, country, product), which **metrics** you can calculate (revenue, sessions, ROAS), and how tables join to each other.

Interact compiles every semantic question into SQL and runs it in your own warehouse. Your data stays where it is; Interact only stores the model definitions.

The semantic layer is used by:

* **Marketing reports** (performance, paid performance, attribution, product performance)
* **Reports** and their widgets
* **Monitors** that track metrics over time
* **Data Analyst agents**, which can query semantic models next to writing their own SQL

## Two kinds of models

Open **Settings → Semantic layer** to see both kinds side by side.

| | Interact models | Custom models |
| - | - | - |
| **Tab** | Interact models | Custom models |
| **Defined by** | Turntwo, built into Interact | You, as YAML files in a Git repository |
| **How you set it up** | Map your tables in **Settings → Data mapping** | Connect a GitHub repository and sync it |
| **Dataset names** | Start with `interact_` (for example `interact_orders`) | Any name you choose |
| **Powers** | Marketing reports, out-of-the-box metrics | Your own business metrics and tables |

> [card] [Set up Interact models](https://docs.getinteract.com/org-settings/semantic-layer/data-mapping.md)
>
> Connect your warehouse and map your tables to the Interact data contract.

> [card] [Add custom models](https://docs.getinteract.com/org-settings/semantic-layer/custom-models.md)
>
> Sync your own Ossie YAML models from a dbt or Dataform repository.

## How the two combine

Interact loads the Interact models first and adds your custom models on top. Both are available in the same query, so a custom model can define a relationship to an Interact model.

> [!WARNING]
>
> Interact models always win a name collision. If a custom dataset has the same name as an Interact dataset, the custom one is ignored and shows an **Unused** badge in the **Custom models** tab. Relationships that point to the ignored dataset are dropped too. Rename the custom dataset to use it.

## Which warehouse connection runs the queries

| Who queries | Connection used |
| - | - |
| Reports, marketing pages, monitors | The **Warehouse - read** connector in **Settings → Data mapping** |
| Data Analyst agents | The agent's own warehouse connection |

Make sure the connector you use can read every table your models point to. See [Data mapping](https://docs.getinteract.com/org-settings/semantic-layer/data-mapping.md#connection) for setting the read connector.

## Who can manage it

Only organization admins can open **Data mapping** and **Semantic layer** in Settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.