Audience | Data or analytics engineers, platform admins, technical marketers |
Prerequisites |
|
Schema setup is a one-time configuration that determines what data marketers can use in the Customer Studio audience builder. It defines models, relationships, and events for audience filtering.
Learning objectives
After reading this article, you'll know how to:
-
Configure parent, related, and event models.
-
Define relationships and join keys across datasets.
-
Understand cardinality, merge columns, and sampling.
-
Align schema structure with marketer use cases.
Overview
Before marketers can define audiences visually, data teams or admins must first set up the schema. You’ll define:
- Parent model: Base entity audiences are built from (e.g. Users)
- Related models: Additional context joined to the parent (e.g., Purchases)
- Event models: Timestamped user behaviors (e.g., Product Viewed)
Once configured, marketers can create dynamic audiences using warehouse data.
What is a data schema?
Let’s say you run an online plant store. You want to target customers in the Midwest who recently bought a succulent.
To build this audience, Hightouch needs to know:
- Who your customers are (Users table)
- What they’ve done (Purchases table with items bought)
Together, these models form your data schema—a map of what’s available to filter on when building an audience.
Together, these models and their relationships form your schema—a map of available filters for marketers. Hightouch handles joins automatically so marketers can apply filters like "users who purchased succulents within the last 30 days” without using SQL or involving engineers.
Coordinate with business teams
Before building your schema, align with marketers or campaign owners on:
- Which entities they’ll target (e.g., Users, Accounts)
- What attributes or behaviors they want to filter on
- Whether real-time or batch syncs are part of their workflow
- How frequently audiences will update
Use this input to decide:
- Which tables or views to expose
- What fields and relationships to define
- How to name models and columns clearly for non-technical users
Schema setup
1. Define the parent model
The parent model is the core dataset for audience building—most commonly a Users table, but it could also be Accounts, Households, or Devices.
Requirements:
-
One row per entity (e.g. one row per user)
-
A stable, unique primary key (e.g.
user_id
) -
Fields useful for filtering (e.g.
email
,region
,created_at
)
To create a parent model:
-
Go to Customer Studio → Schema
-
Click Create parent model
-
By default, Hightouch prompts you to select a table in your source. If you prefer to use another modeling method to define your model, you can select from the following in the dropdown:
- Table selector (default)
- SQL query
- dbt model
- dbt Cloud model
- Looker model
- Sigma model
-
After previewing the result set, click Continue to configure your model:
Field | Description | Example |
---|---|---|
Name | Display name in Customer Studio | Users |
Description (optional) | Helpful context for your team | Represents end users of the platform |
Primary key | Unique ID column | user_id |
Primary label | Display name in audience previews | full_name or email |
Secondary label (optional) | Additional preview context | signup_date |
-
Click Create parent model.
2. Add related models
Related models join to the parent via a foreign key and provide additional filtering context—like purchases, subscriptions, or devices.
Examples:
-
Purchases linked to Users by
user_id
-
Subscriptions linked to Companies by
company_id
To create a related model:
-
Go to Customer Studio → Schema
-
Click the + icon next to your parent model
-
Select Create related model
-
Choose your table or modeling method and preview results
-
Configure the relationship:
Field | Description | Example |
---|---|---|
Name | Related model name | Purchases |
Description (optional) | Context for marketers | User purchase records |
Relationship | Cardinality (1:many , etc.) | 1:many (one user → many purchases) |
Foreign key (join key) | Column joining models | user_id |
To match on multiple columns (e.g., product_id
and location_id
), enable multiple join keys in the relationship configuration.
-
Click Create related model
Use clear names that align with business terms—this makes it easier for marketers to understand and use your schema.
3. Add event models
Event models represent timestamped user behaviors like page views, logins, or checkouts. These power both real-time and historical audience logic.
Requirements:
-
At least one timestamp column (e.g.
created_at
) -
A foreign key linking to the parent model (e.g.
user_id
)
To create an event model:
-
Go to Customer Studio → Schema
-
Click the
+
icon next to your parent model -
Select Create related event
-
Choose your table or modeling method and preview results
-
Click Continue
-
Configure the following:
Field | Description | Example |
---|---|---|
Name | Event name | Product Viewed |
Description (optional) | Context for marketers | Tracks user product views |
Timestamp column | When the event occurred | created_at |
Event type | Category (Generic , Checkout ) | Generic |
Primary key (optional) | For referencing or triggering Journeys | event_id |
Relationship | Cardinality to parent | 1:many (one user → many events) |
Foreign key (join key) | Column joining event with parent | user_id |
- Set the Relationship to your parent model:
- Cardinality is typically
1:many
(one user has many events) - Choose the foreign key from the event model that links back to the parent (e.g.
user_id
)
- Cardinality is typically
- Click Create event
If all events live in a single table, you can create multiple event models by filtering by event type (e.g., Page View
, Add to Cart
).
Relationships and cardinality
Relationships determine how data is joined behind the scenes. You can define:
- Cardinality:
1:1
,1:many
,many:1
- Join direction: parent-to-child or child-to-parent
- Multiple join keys: when matching across two or more columns
- Through relationships: when connecting via an intermediate model
Relationship | Use when... | Example |
---|---|---|
1:many | One parent maps to many related records | One user has many purchases |
1:1 | One parent maps to one related record | A company has one active subscription |
many:1 | Many parent records share one related record | Many users belong to one household |
Use 1:many for most behavioral data (e.g., purchases, page views). Use many:1 when referencing shared objects like plans or organizations.
You can enable multiple join keys using the toggle in the relationship setup. This is helpful when you need to match on compound keys (e.g., product_id
and location_id
).
Optional configurations
Through relationships
Through relationships let you connect two models via an intermediate model. They're useful when you have a many-to-many scenario.
For example, to link users to subscriptions through memberships:
Example: Users → Memberships → Subscriptions
- Users join to Memberships on
user_id
- Memberships join to Subscriptions on
subscription_id
This enables filters like "users with an active subscription" without duplicating logic.
How to set up a through relationship:
Through relationships are configured in the Relationships tab of your parent model.
-
Create the two direct relationships first:
-
Users → Memberships (1:many)
-
Memberships → Subscriptions (many:1)
-
-
In Customer Studio → Schema:
-
Select your parent model (e.g.,
Users
) -
Navigate to the Relationships tab
-
Click Add through relationship
-
-
Under Access, select the model you want to access (e.g.,
Products
). -
In the through dropdown, choose the indirect path that connects your parent model to the target model (e.g.,
Purchases
→Products
). -
Click Save
Once created, this through relationship is available for audience building, traits, and filtering—making it easy for marketers to use indirect data.
Enable Sampling (recommended)
Sampling creates a smaller subset of your data, helping marketers preview audience results faster.
Benefits:
-
Quickly validate filters and trait logic
-
Improves audience preview load times
To enable sampling:
-
Go to Customer Studio → Schema
-
Select your parent model (e.g.,
Users
). -
Click the Sampling tab.
-
Turn on Enable model sampling
-
Configure sampling settings:
Field | Description | Recommended |
---|---|---|
Sample size | Percentage of parent model to sample | 10%–20% |
Sample frequency | How often the sample data updates | Daily |
Related models | Select which related models to sample alongside the parent | Purchases , Subscriptions |
Adjust sample size based on data volume (lower % for very large tables).
- Click Save & run sampling to apply.
Marketers will now experience faster loading audience previews and insights.
Learn more: Sampling →
Manage schema
View and edit your schema
To access your schema:
- Go to Customer Studio → Schema
- Select a parent model to open its configuration view.
- Use the tabs across the top to explore:
- Columns: Preview the model and its available fields
- Query: View the source query or table
- Relationships: View and manage related and event models
- Activity: Audit changes and sync usage
- Sampling: Configure performance settings for previews
To update a model:
- Click the pencil icon next to the model name or field
- Make your changes and click Save
To delete a model:
- Click the three-dot menu and select Delete model
Deleting a model removes it from the audience builder. Any audiences using the model will break and must be updated.
Add or update relationships
To add a new related or event model:
- In the Relationships tab of your parent model, click + Add model
- Choose Create related model or Create related event
- Follow the configuration steps
To update an existing relationship:
- Hover over the relationship and click the pencil icon
- You can change join keys, rename the model, or adjust cardinality
You can define relationships using multiple join keys by selecting "Multiple join keys" in the model editor.
Monitor schema usage
To understand how your schema is being used:
-
Use the Activity tab on each model to track:
- Recent updates to the model definition
- Audiences, traits, or syncs that reference this model
- Sync history and errors
This can help you identify unused models, resolve sync issues, or clean up deprecated fields.
What’s next?
After defining your schema, choose one of two next steps based on your role:
If you're managing governance and delivery:
Set up rules that control how data flows to destinations and how consent is enforced:
-
Destination rules → Define sync behavior, redaction policies, and delivery restrictions per destination.
-
Subsets →
Apply destination-specific filters (e.g., opt-outs) without changing the core audience logic. -
OneTrust Snowflake Native App → Enforce consent policies using Snowflake-native integration with OneTrust.
If you're a marketer:
Once the schema is in place, marketers and campaign teams can begin building audiences:
- Audiences → Use filters, traits, and events to define dynamic segments directly from your data.