Search documentation...


Define a data schema

Audiences is available as an add-on on Business Tier plans.


Creating an audience requires having a parent model to draw data from. You define a parent model like any other model. You can optionally create related models and events to tie to your parent model and boost your filtering capabilities.

The parent model, related objects, and events, are configured in the Setup tab. The setup tab is divided into Parent Models, Related Models and Events.

Schema page

An example schema

For example, Amazon might map the following schema from their warehouse to Hightouch:

  • A parent model of users (which you build audiences off of). With columns for:
    • user_id: a unique identifier for the user. Used as a foreign key for other tables.
    • name: the user's name
    • age: the user's age
  • A "purchases" object, with columns for:
    • user_id: A reference to the user that made the purchase
    • total: The total cost of the purchase
    • used_coupon: Whether the user used a coupon when checking out
  • A "viewed page" event, with columns for:
    • user_id: A reference to the user that viewed the page
    • page_path: The URL path for the page (for example, /promo)
    • timestamp: When the user viewed the page


The parent model table

The parent model table is defined under the "Setup" section. You can create these queries just like any other query in Hightouch. The parent must have a primary key so that it can be synced to a destination.

Note: The parent model typically consists of a list of users. Each row should be unique and no duplicates should be present in your parent model.

Users query with table selector

Other objects

Other objects are defined under the "objects" section as well. These objects can be referenced in the "related object" filter, but can't be directly synced.

For example, you may create a second object for "organizations," so that users that are a part of an organization can be filtered based on properties of the organization.


Under the hood, Hightouch generates SQL JOINs between your various models to power the related object and event conditions. To facilitate this, you need to configure the foreign keys between your models.

Direct relationships

In the majority of cases, you only need to setup "direct relationships," which relate models directly to each other. That is, the users table's foreign key is directly referenced by the other model.

For example, for the schema above, you need a relationship between "users" and "purchases":

Example direct relationship

Many to many relationships

Hightouch supports objects that are related through an intermediary table. For this reason, many to many relationships are also known as "through relationships."

For example, a user might belong to multiple organizations. Imagine you have:

  • A users table, with columns for:
    • user_id: a unique identifier for the user
  • A organizations table, with columns for:
    • organization_id: a unique identifier for the organization
  • A memberships table (where a user is "part of" an organization" if they have an entry with a matching user_id and organization_id), with columns for:
    • user_id: A reference to the user
    • organization_id: A reference to the organization

In this example, you could say "users are related to organizations through the memberships table." And create the following relationships to allow for the filtering of users based on organization properties:

  • A direct relationship from users to memberships on user_id
  • A direct relationship from memberships to organizations on organization_id
  • A through relationship from users to memberships via the above two direct relationships.

In general, you should just create direct relationships, and only use through relationships if you have to.


Events are very similar to related objects—you just have to specify the name of the timestamp column.

Each event should have its own query, as well as a relationship from the users model to the event.

Example event definition

Example event relationship

    Need help?

    Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

    • Connection issues with your data warehouse?
    • Confusing API responses from destination systems?
    • Unsupported destination objects or modes?
    • Help with complex SQL queries?

    Feature Requests?

    If you see something that's missing from our app, let us know and we'll work with you to build it!

    We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.

On this page

OverviewAn example schemaObjectsThe parent model tableOther objectsRelationshipsDirect relationshipsMany to many relationshipsEvents

Was this page helpful?