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.
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
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.
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.
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 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.
You can then select to Preview 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.
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.
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.