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

# Data mapping

> Connect your warehouse and map your tables to the Interact data contract to load the built-in Interact models.

## Overview

Interact models are semantic models that Turntwo maintains. They follow a fixed table layout, the **data contract**: you deliver tables with the agreed columns in your warehouse, and point Interact at them in **Settings → Data mapping**. Interact then builds the `interact_*` datasets and the marketing reports on top of them.

Your data stays in your warehouse. Interact reads it with your connector at query time.

**Prerequisites:**

* You are an organization admin
* A [Google BigQuery connector](https://docs.getinteract.com/org-settings/connectors/bigquery.md) in **Settings → Connectors**
* Contract tables delivered in a BigQuery dataset (by default named `ext_interact__<table>`; see [Tables](#tables))
* An existing, empty dataset where Interact can write its own tables

The Data mapping page has four tabs: **Connection**, **Table mapping**, **Label mapping** and **Schemas**. One **Save** button saves all tabs.

***

## Connection

### Warehouse - write

The connector and dataset where Interact writes its own tables, such as business events, attribution results and precalculated marketing tables.

| Field | Required | Description |
| - | - | - |
| **Connector** | Yes | A BigQuery connector. Its service account needs write access to the dataset below. |
| **Dataset / schema** | Yes | The dataset Interact writes to, for example `src_interact`. |

> [!WARNING]
>
> The destination dataset must already exist. Interact does not create it.

### Timezone

The calendar used for warehouse dates and semantic queries, for example when a report asks for "yesterday" or "last week". Defaults to `Europe/Amsterdam`.

### Warehouse - read

The connector that reads the contract tables and runs every semantic query for reports, marketing pages and monitors. Agents use their own warehouse connection instead.

| Field | Required | Description |
| - | - | - |
| **Connector** | Yes | A BigQuery connector that can read the contract dataset and any tables your custom models use. |

> [!TIP]
>
> The read and write connector can be the same connector. Use separate connectors when you want reports to run with read-only credentials.

***

## Table mapping

### Dataset

Enter the **Dataset / schema** that holds the delivered contract tables, for example `ext_interact`.

### Tables

Switch on each table you deliver and enter its table name. Hover the info icon next to a table for a short description of what it holds. Tables with a **Performance** badge are needed for the marketing performance reports.

| Table | Default table name | Performance | Required columns |
| - | - | - | - |
| Campaign mapping | `ext_interact__campaign_mapping` | Yes | `label`, `label_country`, `source_group`, `campaign_id` |
| Channel metrics | `ext_interact__channel_metrics` | Yes | `date`, `label`, `label_country`, `source_group` |
| Sessions | `ext_interact__sessions` | Yes | `session_id`, `session_created_at`, `label`, `label_country` |
| Conversions | `ext_interact__conversions` | Yes | `conversion_id`, `conversion_type`, `conversion_created_at`, `label`, `label_country` |
| Orders | `ext_interact__orders` | Yes | `order_id`, `order_created_at`, `label`, `label_country` |
| Session products | `ext_interact__session_products` | No | `session_id`, `product_id`, `date`, `label`, `label_country` |
| Order lines | `ext_interact__order_lines` | No | `line_id`, `order_id`, `order_created_at`, `label`, `label_country`, `product_id` |
| Products | `ext_interact__products` | No | `product_id`, `label`, `label_country` |
| Product price and stock | `ext_interact__product_price_stock` | No | `date`, `label`, `label_country`, `group_product_id` |
| Product cost | `ext_interact__product_cost` | No | `date`, `label`, `label_country`, `group_product_id` |
| Customers | `ext_interact__customers` | No | `customer_id`, `label`, `label_country` |
| Context events | `ext_interact__context_events` | No | `id`, `date_start` |
| Targets and budgets | `ext_interact__targets` | No | `date`, `grain`, `label`, `label_country`, `kind`, `metric`, `value` |

Only the required columns must exist. Every other contract column is optional: when a table doesn't have it, Interact reads it as an empty value of the right type. The **Schemas** tab lists all columns per table.

Each mapped table becomes an Interact dataset named `interact_<table>`, for example `interact_orders`. You can see them in **Settings → Semantic layer → Interact models**.

### Custom parameters

Each contract table may have a `custom_params` struct column with your own extra fields. When you save, Interact scans the struct:

* **Numeric fields** (`INT64`, `FLOAT64`, `NUMERIC`, `BIGNUMERIC`) become **metrics**. They show as badges under the table.
* **All other fields** become **dimensions**.

Field names must start with a letter or underscore and contain only letters, numbers and underscores. Nested structs inside `custom_params` are skipped.

> [!NOTE]
>
> The scan runs on save. After you add a field to `custom_params` in the warehouse, open Data mapping and click **Save** again to pick it up.

***

## Label mapping

Contract tables use a `label` column (brand, shop or business unit) and a `label_country` column. Map the raw warehouse values to the names your team sees in reports.

| Section | Columns | Description |
| - | - | - |
| **Label mapping** | Value, Display name, Default, Logo | Maps a `label` value (for example `label_x`) to a display name. Upload an optional logo per label (PNG, JPEG, WebP or SVG). |
| **Country mapping** | Value, Display name, Default | Maps a `label_country` value to a display name (for example `Netherlands`). |

Reports open on the label and country marked as **Default**.

***

## Schemas

The **Schemas** tab is the reference for every contract table: each column with its kind (dimension or metric), type, description and whether it is required.

After you save, Interact checks each mapped table against the contract. Required columns your table does not have are marked **Missing**. Scanned `custom_params` metrics are listed too.

> [!TIP]
>
> Share a link to a single table: the Schemas tab updates the URL with the table key, for example `#orders`.

***

## Troubleshooting

> [accordion] No warehouse connectors to select
>
> Data mapping only lists active BigQuery connectors. Add one in **Settings → Connectors** first. See [Google BigQuery](https://docs.getinteract.com/org-settings/connectors/bigquery.md).

> [accordion] A column shows as Missing
>
> The mapped table lacks a required column. Add the column to the table in your warehouse, then save Data mapping again.

> [accordion] Interact models tab is empty
>
> No contract tables are switched on yet, or the dataset field is empty. Switch on at least one table in **Table mapping** and save.

> [accordion] A custom\_params field isn't showing as a metric
>
> Only numeric types become metrics; strings, booleans and dates become dimensions. Also check the field name format, and save Data mapping again after changing the table.


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