Search documentation...

ChangelogBook a demoSign up

Models overview

To learn about defining data models for Audiences, refer to the Customer Studio documentation.

Hightouch models define and organize the data you want to query from a source.

Model diagram

To create a new model, navigate to the Models page and click Add model. Next, select one of you the sources you've setup. Then choose a modeling method:

  • SQL editor
  • Table selector
  • dbt model selector
  • Looker
  • Sigma

Modeling methods in the Hightouch app

Supported modeling methods depend on the source. Refer to source documentation to learn about supported modeling methods.

Refer to the SQL editor and table selector docs for details on how to use those modeling methods.

Refer to the Extensions documentation to learn more about how to connect Hightouch to these platforms and build Hightouch models using existing dbt models, Looker Looks, or Sigma workbooks.

Unique primary key requirement

Regardless of how you build your models, you must configure them with a unique primary key. To configure a model's primary key, select the column with unique values from your dataset when prompted during model setup.

Selecting a primary key in the Hightouch app

To ensure your destinations receive all desired data, it's imperative to select a truly unique primary key. Hightouch uses this unique identifier to keep track of records. Using a unique key lets Hightouch sync only new and updated data to your destinations. See the change data capture docs to learn how Hightouch accomplishes this.

Make sure to read through the primary key updates section before making any changes to your primary key.

If your dataset doesn't inherently include any truly unique columns, you can use the SQL editor to either filter out duplicate rows or create a composite column to use for your primary key. If you're not using the SQL modeling method or if SQL isn't supported by your source, you need to make changes to your data upstream to ensure it includes a unique column.

Hightouch intentionally stringifies your chosen primary key column for enhanced performance during change data capture. If you need to sync the primary key column as a non-string value, use SQL aliasing in your model to create a new column specifically for syncing.

Primary key updates

If you update a model's primary key by selecting a different column, you need to trigger a full resync for all syncs that use that model. Otherwise, change data capture can't process your model data correctly, which can make your syncs fail.

You don't need to manually trigger a full resync if you change the primary key column's data type. If you change the primary key's data type in the model configuration, your sync will process normally. If you make this change in your source or in the SQL editor, the entire model query result set is automatically resynced as if you triggered a full resync. As outlined in the full resync prerequisites section, this can create duplicates in your destination data.

Data types and casting

When you define a model, Hightouch doesn't change the data types found in your source unless otherwise specified. You can view a column's type in a model's Columns tab.

Modeling methods in the Hightouch app

To safeguard your syncs from failing, the data types your model returns must align with your destination's data type expectations. If your source data types don't match your destination's expectations, you can use data casting while setting up your models.

Preview model results

When first defining a model, it's highly recommened to Preview results before you continue with setup. Previewing lets you validate the data your model returns before syncing it to downstream destinations.

Previewing a new model's query results

Previewing a model's query results can also be helpful when troubleshooting issues. To preview an existing model's results, open the model's overview page and click Edit.

Previewing an existing model's query results

You can then select to Preview results.

Previewing an existing model's query results

If you want to display all model rows, click the gear symbol, then toggle off Limit preview to 100 rows. You can also turn off Show row count to improve loading performance for larger data models.

Column descriptions

You can add descriptions to your models' columns so that team members (and your future self) can more easily understand the data. Go to a model's Columns tab and click the a column's description to edit it.

Editing column descriptions in the Hightouch app

If you're using the dbt extension to build models, Hightouch automatically pulls in columns descriptions from dbt.

Clone models

After creating a model, you can clone it by opening the horizontal three-dot menu on its overview page and clicking Clone.

Cloning a model in the Hightouch app

This opens a new page where you can:

  • edit and preview the cloned model's query
  • select which syncs to clone, if the model you're cloning has syncs associated with it
  • give it a custom name and description
  • confirm which model column to use as the primary key

Once you finish creating the cloned model, you can further edit it and configure additional syncs on it, like any other model.

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.

Last updated: Oct 4, 2023

On this page

Unique primary key requirementPrimary key updatesData types and castingPreview model resultsColumn descriptionsClone models

Was this page helpful?