| Audience | Data teams setting up their first activation in Hightouch |
| Prerequisites | A Hightouch workspace with permission to create sources, models, destinations, and syncs. |
A sync sends the rows your model returns to a destination — a tool or app your team already works in. This guide takes you from an empty workspace to a running sync in four steps.
A sync depends on three things existing first, so you build them in order:
- Connect a source — where your data lives.
- Set up a model — the query that selects the rows to send.
- Connect a destination — where the data lands.
- Configure the sync — how and when the rows are sent.
If you already have a source, model, or destination, skip ahead to Configure the sync. New to Hightouch? Review the core concepts first.
Connect a source
A source is where your organization's data lives, such as a data warehouse or database.
- Go to the Sources overview and click Add source.
- Select the source you want to add.
To test things out without a production source, use the B2B SaaS or B2C eCommerce Sample datasets. They're at the end of the source list and need no credentials.
- Enter the source's credentials. These differ by source. See the source documentation for details.
- Click Continue. Hightouch tests the connection before it saves. If the test fails, re-enter your credentials.
- Give the source a Source name. Include the environment and data it holds, especially if you'll connect more than one instance of the same source, such as a development and a production version.
- Click Finish.
The source now appears on the Sources overview, ready to build models against.
Set up a model
A model defines which rows to pull from your source.
- Go to the Models overview and click Add model.
- Select the source you connected.
- Choose a modeling method: SQL editor, table selector, dbt model, or Looker Look. The Sample datasets come with pre-populated SQL.
- Preview the query, then click Continue. The preview shows the first 100 rows so you can confirm the model returns the records you intend to activate before you go further.
- Give the model a Model name that describes its contents and purpose.
- Select a Primary key — a column whose values are unique and stable for every row. Change data capture uses the primary key to track which rows were added, changed, or removed between runs, so a stable key is what lets syncs send diffs instead of everything. See change data capture for why this matters.
- Click Finish.
The model now appears on the Models overview.
Connect a destination
A destination is the tool or app you want to receive your data. Connect it before you configure the sync.
- Go to the Destinations overview and click Add destination.
- Select the destination you want to add and click Continue.
To test things out without a production destination, use Google Sheets. It's a lite destination and quick to set up.
- Authorize the connection or enter the destination's credentials. These differ by destination. See the destination documentation for details.
- Click Continue. Hightouch tests the connection before it saves. If the test fails, re-enter your credentials.
- Give the destination a Destination name.
- Click Finish.
The destination now appears on the Destinations overview.
Configure the sync
A sync declares how your model's rows appear in the destination. With a source, model, and destination in place, create it in the sync wizard.
- Go to the Syncs overview and click Add sync.
- Select the model to pull data from.
- Select the destination to send data to.
- Configure how the sync writes to the destination. The options here are destination-specific, but most syncs involve three decisions:
| Decision | What you choose | Guidance |
|---|---|---|
| Sync type and mode | The object to write to and whether to insert, update, or upsert records. | Choose a sync type and mode |
| Record matching | The destination field and model column used to find the right record. | Match records to destination records |
| Field mapping | Which model columns map to which destination fields. | Map model columns to destination fields |
- Click Continue.
- Name the sync and set its schedule. A schedule is required — even "manual only" is a choice. See schedule a sync for the available schedule types.
- Click Finish.
You land on the sync's overview page, where you can run it, edit its Configuration and Schedule, set up alerts, and open the debugger to inspect past runs.
Run and verify your first sync
The sync doesn't run on its own until its schedule fires. To run it now, click Run.
When the run finishes, confirm it did what you expected:
- Row count — the number of rows the sync attempted matches the row count from your model preview.
- Operation type — the run added, changed, or removed the rows you expected. The first run of an upsert sync usually adds every row.
- Rejected rows — the run rejected zero rows. A run can succeed at the top level while individual rows fail, so check this even on a successful run.
- Destination record — open one record in the destination and confirm the mapped fields arrived with the right values.
If the result is unexpected
- Rejected rows or a failed run — open the run and use the debugger to inspect the request and response for a specific row.
- A known error message — look it up in the sync error codes reference.
- Wrong records updated — recheck your record matching column. A non-unique matching field can update the wrong destination record.
- Wrong or missing field values — recheck your field mapping.
Next steps
- Schedule the sync to run on the cadence your workflow needs.
- Configure alerts so you're notified when a run fails.
- Understand change data capture to see how Hightouch decides what to send on each run.