ChangelogBook a demoSign up

Define data schema

AudienceData or analytics engineers, platform admins, technical marketers
Prerequisites
  • A connected data source (e.g., Snowflake, BigQuery, Databricks)
  • Technical understanding of your data and its relationships

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.

Audience example

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.

Audience example

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:

  1. Go to Customer Studio → Schema

  2. Click Create parent model

    Create parent model

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

    Select modeling method

    Continue setup

  4. After previewing the result set, click Continue to configure your model:

FieldDescriptionExample
NameDisplay name in Customer StudioUsers
Description (optional)Helpful context for your teamRepresents end users of the platform
Primary keyUnique ID columnuser_id
Primary labelDisplay name in audience previewsfull_name or email
Secondary label (optional)Additional preview contextsignup_date
Column suggestions are enabled by default to help marketers discover useful filters.
  1. Click Create parent model.

    Configure model

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

  1. Go to Customer Studio → Schema

  2. Click the + icon next to your parent model

  3. Select Create related model

    Create related model

  4. Choose your table or modeling method and preview results

  5. Configure the relationship:

FieldDescriptionExample
NameRelated model namePurchases
Description (optional)Context for marketersUser purchase records
RelationshipCardinality (1:many, etc.)1:many (one user → many purchases)
Foreign key (join key)Column joining modelsuser_id

To match on multiple columns (e.g., product_id and location_id), enable multiple join keys in the relationship configuration.

The primary key uniquely identifies rows. The join key connects tables.
  1. Click Create related model

    Configure 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:

  1. Go to Customer Studio → Schema

  2. Click the + icon next to your parent model

  3. Select Create related event

    Create event

  4. Choose your table or modeling method and preview results

  5. Click Continue

    New event

  6. Configure the following:

FieldDescriptionExample
NameEvent nameProduct Viewed
Description (optional)Context for marketersTracks user product views
Timestamp columnWhen the event occurredcreated_at
Event typeCategory (Generic, Checkout)Generic
Primary key (optional)For referencing or triggering Journeysevent_id
RelationshipCardinality to parent1:many (one user → many events)
Foreign key (join key)Column joining event with parentuser_id
The primary key uniquely identifies a row. The join key links it to another model. Often, the primary key in the parent model becomes the join key in a related model, but they serve distinct purposes.
  1. 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)
  2. Click Create event
    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
RelationshipUse when...Example
1:manyOne parent maps to many related recordsOne user has many purchases
1:1One parent maps to one related recordA company has one active subscription
many:1Many parent records share one related recordMany 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.

Entity relationship diagram model

How to set up a through relationship:

Through relationships are configured in the Relationships tab of your parent model.

  1. Create the two direct relationships first:

    • Users → Memberships (1:many)

    • Memberships → Subscriptions (many:1)

    Intermediate table

  2. In Customer Studio → Schema:

    • Select your parent model (e.g., Users)

    • Navigate to the Relationships tab

    • Click Add through relationship

    Add through relationship

  3. Under Access, select the model you want to access (e.g., Products).

    Select model

  4. In the through dropdown, choose the indirect path that connects your parent model to the target model (e.g., PurchasesProducts).

    Choose path

  5. Click Save

Once created, this through relationship is available for audience building, traits, and filtering—making it easy for marketers to use indirect data.

Use clear and descriptive names when creating through relationships. This helps marketers easily identify and apply the relationships during audience setup.

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:

  1. Go to Customer Studio → Schema

  2. Select your parent model (e.g., Users).

  3. Click the Sampling tab.

  4. Turn on Enable model sampling

    Enable sampling

  5. Configure sampling settings:

FieldDescriptionRecommended
Sample sizePercentage of parent model to sample10%–20%
Sample frequencyHow often the sample data updatesDaily
Related modelsSelect which related models to sample alongside the parentPurchases, Subscriptions

Adjust sample size based on data volume (lower % for very large tables).

  1. 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:

  1. Go to Customer Studio → Schema
  2. Select a parent model to open its configuration view.
  3. 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:

  1. In the Relationships tab of your parent model, click + Add model
  2. Choose Create related model or Create related event
  3. 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

    Activity

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:

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.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Privacy PolicyTerms of Service

Last updated: Jul 30, 2025

On this page
  • Learning objectives
  • Overview
  • What is a data schema?
  • Coordinate with business teams
  • Schema setup
  • 1. Define the parent model
  • 2. Add related models
  • 3. Add event models
  • Relationships and cardinality
  • Optional configurations
  • Through relationships
  • Enable Sampling (recommended)
  • Manage schema
  • View and edit your schema
  • Add or update relationships
  • Monitor schema usage
  • What’s next?

Was this page helpful?