> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Syncs overview

> A sync sends the rows a model returns to a destination, and defines how and when that data lands.

![Sync to Destination](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/syncs-diagram-text.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a8457185a1526d39eb5985827d192f32)

## How a sync works

A sync connects one model to one destination object, list, or table, and describes how the model's rows map into that destination. It has four parts you configure once:

* **Model** — the query results to send.
* **Sync type and mode** — the destination object to write to and whether to insert, update, or upsert records.
* **Record matching** — the field the destination uses to find the right record.
* **Field mapping** — which model columns land in which destination fields.

Between runs, Hightouch uses [change data capture](https://docs.hightouch.com/syncs/cdc.md) to compare the current model results against the previous run and send only the rows that were added, changed, or removed. That's why the first run usually adds every row and later runs send far fewer.

A sync runs on the schedule or trigger you set, then reports the outcome of each run so you can confirm it worked.

## Choose a task

Most work with a sync starts from one of these goals:

| If you want to... | Go to |
| - | - |
| Create a sync from scratch | [Create your first sync](https://docs.hightouch.com/syncs/create-your-first-sync.md) |
| Choose how records are written to the destination | [Choose a sync type and mode](https://docs.hightouch.com/syncs/types-and-modes.md) |
| Match source rows to the right destination records | [Match records to destination records](https://docs.hightouch.com/syncs/record-matching.md) |
| Map model columns to destination fields | [Map model columns to destination fields](https://docs.hightouch.com/syncs/mapping-data.md) |
| Set when the sync runs | [Schedule a sync](https://docs.hightouch.com/syncs/schedule-sync-ui.md) |
| Check a run or debug rejected rows | [Debug a sync run](https://docs.hightouch.com/syncs/debugger.md) |
| Understand why rows retry | [Sync retries](https://docs.hightouch.com/syncs/retries.md) |
| Get notified when a run fails | [Configure sync alerts](https://docs.hightouch.com/syncs/alerting.md) |
| Analyze run history in your warehouse | [Warehouse Sync Logs](https://docs.hightouch.com/syncs/warehouse-sync-logs.md) |
| Reprocess or reset a sync's state | [Resync full query](https://docs.hightouch.com/syncs/resync-reset-clear.md#full-resync), [Reset CDC](https://docs.hightouch.com/syncs/resync-reset-clear.md#reset-cdc), or [Clear and fill](https://docs.hightouch.com/syncs/resync-reset-clear.md#clear-and-fill) |

## Sync families

"Sync" is an umbrella term. Most syncs are standard batch syncs that evaluate a model on a schedule, but the semantics differ across families, so a behavior that's true for one isn't always true for another:

* **Batch syncs** — evaluate a model on a schedule or trigger. The default, and what the rest of this page describes.
* **Audience syncs** — created from [Customer Studio](https://docs.hightouch.com/customer-studio/overview.md) audiences. The audience defines membership; the sync activates it.
* **Realtime syncs** — react to membership or event changes through [Real-Time Personalization](https://docs.hightouch.com/real-time/overview.md) on separate infrastructure, not a batch schedule.
* **Journey-triggered syncs** — run when a [journey](https://docs.hightouch.com/customer-studio/journeys.md) evaluates a member, not on a fixed cadence.

## What varies by destination

The available sync types, modes, matching keys, fields, delete behavior, and limits are defined by each destination. The sections below cover the shared model; for the specifics of any integration, see its [destination documentation](https://docs.hightouch.com/destinations/overview.md).

## Syncs overview page

Hightouch lists all syncs, both active and inactive, on the [**Syncs** overview](https://app.hightouch.com/syncs?from=docs) page.

![The all syncs list in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/all-syncs-list.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=eb673e30e8759dce8fe044e3bda8c4c5)

For each sync, the list shows its [**alert state**](https://docs.hightouch.com/syncs/alerting.md), its associated [**model**](https://docs.hightouch.com/getting-started/concepts.md#models) and [**destination**](https://docs.hightouch.com/getting-started/concepts.md#destinations), and its **last run**. Use the folders and filters alongside the list to narrow it by source, destination, label, or [status](#sync-status).

Click a sync to open its [individual overview page](#individual-sync-overview-page).

### Sync status

Hightouch tracks two kinds of status. **Sync health** is the sync's overall condition; **run status** is the state of an individual run. The syncs list can show either, and in workspaces with [advanced alerting](https://docs.hightouch.com/syncs/alerting.md) it shows an **Alerts** column in place of last-run status.

#### Sync health

* **Healthy**: the most recent run completed
* **Warning**: the most recent run completed with rejected rows
* **Pending**: the sync hasn't run yet
* **Disabled**: the sync is turned off

#### Run status

* **Querying**: the run is reading its model
* **Preparing** / **Processing**: the run is preparing data for the destination
* **Queued**: the run is waiting to start
* **In progress**: the run is writing to the destination
* **Completed**: the run finished
* **Completed with errors**: the run finished, but the destination rejected some rows
* **Interrupted**: a temporary interruption stopped the run, and it resumes on the next run
* **Aborted**: the run was stopped before it finished
* **Failed**: an error stopped the run. Open the run to see why.

## Individual sync overview page

Click a sync on the [**Syncs** overview](https://app.hightouch.com/syncs?from=docs) to open its own page.

The page shows the sync's model and destination, whether it's **enabled** or **disabled**, a **Run sync** button to run it manually, and a **...** menu to move the sync to a [folder](https://docs.hightouch.com/workspace-management/folders-filters.md#folders), edit its labels, [resync or reset](https://docs.hightouch.com/syncs/resync-reset-clear.md#full-resync) it, or delete it. The **Overview** tab summarizes the sync's alert state, its **Recent sync runs**, and **Sync metrics** such as successful operations over time. The panel alongside it holds the sync's schedule, description, labels, and:

* **Sync ID**: the numerical identifier used when setting up an [Airflow](https://docs.hightouch.com/extensions/airflow.md) operator or the [Dagster](https://github.com/hightouchio/dagster-hightouch), [Prefect](https://github.com/PrefectHQ/prefect-hightouch), or [Mage](https://docs.mage.ai/integrations/hightouch) extensions
* **Sync slug**: a human-readable identifier for the sync
* **Created by**: who created the sync, and when

![An individual sync's overview page](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/sync-detail-overview.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6c45c01a9eadeecf6f0e8d4cc7c24ebd)

Use the tabs to view and edit each part of the sync:

* **Configuration**: the sync's [configuration](#configuration).
* **Schedule**: the sync's [schedule](#schedule).
* **Runs**: the status, time, and [details](#run-details) of recent runs. Select a run to open the [debugger](https://docs.hightouch.com/syncs/debugger.md).
* **Alerting**: the sync's [alerts](https://docs.hightouch.com/syncs/alerting.md).
* **Sync logs**: where the sync's [historical logs](https://docs.hightouch.com/syncs/warehouse-sync-logs.md) are stored.
* **Splits**: the [experiment](https://docs.hightouch.com/customer-studio/experiments.md) groups assigned to the sync. Appears when the model uses splits.
* **Activity**: recent changes to the sync's configuration and settings.

These three run-level actions all start from the sync's **...** menu → **Resync or reset...**. For a decision guide, prerequisites, and warnings, see [Resync, reset CDC, or clear and fill](https://docs.hightouch.com/syncs/resync-reset-clear.md).

### Resync full query

A full resync reprocesses every current row as if it were newly **Added**, resetting the sync's tracking to its initial state. See [when it's safe and how to run it](https://docs.hightouch.com/syncs/resync-reset-clear.md#full-resync).

#### Full resync prerequisites

Before you trigger a full resync, check your [sync mode and delete behavior](https://docs.hightouch.com/syncs/resync-reset-clear.md#before-you-begin) — reprocessing every row can create duplicates on insert-mode, event, and webhook syncs.

### Clear and fill

Where a destination supports it, [clear and fill](https://docs.hightouch.com/syncs/resync-reset-clear.md#clear-and-fill) empties a segment or audience and re-fills it from the current model.

### Reset CDC

[Reset CDC](https://docs.hightouch.com/syncs/resync-reset-clear.md#reset-cdc) clears change-data-capture state without sending any rows, so the next run captures a fresh baseline and sends nothing.

### Run details

A run is a single invocation of a sync, triggered manually or on a schedule. The **Runs** tab lists each run with:

* The run's **status**
* The time the run **started** and its duration
* The number of **rows queried**
* The total **operations** — expand it to see rows added, changed, and removed
* The **results**: successful operations in green and rejected operations in red

![The runs list for a sync](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/sync-run-list.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=acb7a3cde1020a7d5458e4eae2a76ace)

Click **View run** to open a run. Its rejected rows appear on the run's **Rejected** tab, each with the destination's error message. To inspect a row's request and response, use the [debugger](https://docs.hightouch.com/syncs/debugger.md).

![A run's rejected rows with error messages](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/run-rejected-rows.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=ad040388d8ee1acbad4b16559a184e86)

### Configuration

The **Configuration** tab exposes destination-specific options. These vary by destination but generally include:

* **Type**: the kind of object to sync to, such as objects, events, or subscription lists. See [types and modes](https://docs.hightouch.com/syncs/types-and-modes.md).
* **Mode**: the update mode, such as upsert, insert, or update. See [types and modes](https://docs.hightouch.com/syncs/types-and-modes.md).
* **Record matching**: for update or upsert modes, how source rows match destination records. See [record matching](https://docs.hightouch.com/syncs/record-matching.md).
* **Field mapping**: which source columns sync to which destination fields. See [field mapping](https://docs.hightouch.com/syncs/mapping-data.md).
* **Batching**: how data is batched into API requests.
* **Delete behavior**: what to do when a record leaves your source.

#### Delete behavior

For some sync types and destinations, you may want to remove records that no longer appear in your model's query results.

For example, you might sync customer records to a CRM from a [model](https://docs.hightouch.com/getting-started/concepts.md#models) of all active users. When a user becomes inactive and drops out of the query results, you may want to delete them or clear their fields in the CRM.

Depending on the destination and sync mode, common delete-behavior options are:

| Behavior | Description |
| - | - |
| **Do nothing** | Keep the record in the destination. Use this when you want the destination to keep accruing records from your source. |
| **Clear fields** | Keep the record but clear the mapped fields. Use this to retain records while emptying the fields your sync maps. |
| **Delete destination record** | Delete the record in the destination. Use this when you want the destination to mirror your source by dropping records that leave your model. |

Hightouch acts on records only as they leave your model's query results, and only *after* you apply deletion settings. It has no access to historically removed records, so it can't delete or clear records that already left your source before this run. It compares against the immediately previous run only. A [full resync](https://docs.hightouch.com/syncs/resync-reset-clear.md#full-resync) doesn't delete or clear historically removed records.

> [!NOTE]
>
> Regardless of the delete-behavior option, a [run's detail
> page](https://docs.hightouch.com/syncs/debugger.md#view-run-details) always displays removed rows.

For a destination's delete-behavior details, see its documentation.

#### Configuration actions

From the configuration, you can also [test a row](#test-a-row) or edit the configuration as a [JSON](#edit-as-json) object.

![The Test and Edit as JSON actions on a sync's configuration](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/sync-config-actions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d7697dfae9f3abf1fcff0b57938739dc)

#### Test a row

Testing a row sends a single row from your model to your destination, so you can confirm the sync works before running it in full.

The **Test** button appears at the top of the configuration when your destination supports row testing for the current setup. If you don't see it, the destination doesn't support testing this configuration — some require specific options first, such as Meta Custom Audiences, which tests only against an existing audience.

Click **Test** and select a row. Before testing, you can edit a column's data type and value by hovering over it, clicking the pencil icon, making the change, and clicking the check mark. You can't edit the model column used for [record matching](https://docs.hightouch.com/syncs/record-matching.md#choose-the-model-column), because Hightouch [intentionally stringifies](https://docs.hightouch.com/models/data-types-casting.md) it for performance.

![The Test a row window with a selected row and its column values](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/test-row-modal.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e49119e4eda5d10df5e914bf6a1f9ceb)

> [!NOTE]
>
> The row-testing window displays only certain [data
> types](https://docs.hightouch.com/models/data-types-casting.md#data-types), such as **string** and
> **number**. A column of another type, such as **date**, shows as **string**.
> This affects the UI only — Hightouch doesn't convert the data type when
> syncing. To confirm a column's type, see the [model
> configuration](https://docs.hightouch.com/models/data-types-casting.md#view-model-data-types) page.

Click **Sync as added row** to send it, or use the **...** menu to sync it as a [changed or removed row](https://docs.hightouch.com/syncs/debugger.md#view-run-details). The request and response appear alongside the row so you can see exactly what Hightouch sent and what the destination returned. The UI may take a few seconds to show results.

![The Test a row window showing the request and response for a synced row](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/test-row-response.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=2845135ad3c02bba5ff26871cfb4da4f)

#### Edit as JSON

You can edit a sync's configuration as JSON to make several changes at once or copy one sync's configuration to another. For example:

```JSON theme={null}
{
    "mode": "upsert",
    "type": "object",
    "fromId": "track_visitor_id",
    "object": "user",
    "mappings": [
        {
            "to": "uuid-western",
            "from": "uuid"
        },
        {
            "to": "Trialer Status",
            "from": "trialer_status"
        }
    ],
    "customMappings": [
        {
            "to": "unique_notification_status",
            "from": "notify_status"
        }
    ]
}
```

### Schedule

Every sync has a schedule, which decides how often it runs. Besides manual runs, you can schedule a sync with these options:

* **Interval**: run on a set interval, such as once a day.
* **Custom recurrence**: run at a specific date and time, such as every Monday at 9 AM.
* **Cron expression**: run on a [cron expression](https://en.wikipedia.org/wiki/Cron).
* **dbt Cloud**: trigger runs from [dbt Cloud](https://docs.hightouch.com/extensions/dbt-cloud.md).
* **Fivetran**: trigger runs from [Fivetran](https://docs.hightouch.com/extensions/fivetran.md).

![Sync scheduling in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/syncs/sync-schedule.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=75c6fd87c6955aad869f42437a5b99c9)

You can also trigger syncs with [Airflow](https://docs.hightouch.com/extensions/airflow.md), [Dagster](https://github.com/hightouchio/dagster-hightouch), [Prefect](https://docs-v1.prefect.io/api/latest/tasks/hightouch.html), [Mage](https://docs.mage.ai/integrations/hightouch), or the [REST API](https://docs.hightouch.com/api-reference/trigger-sync.md), even though these aren't listed as schedule types. For all scheduling options, see [schedule a sync](https://docs.hightouch.com/syncs/schedule-sync-ui.md).

To require one sync to finish before another begins, use [Sequences](https://docs.hightouch.com/syncs/schedule-sync-with-sequences.md). If you're planning around Daylight Saving Time, review the [DST guidance](https://docs.hightouch.com/syncs/schedule-sync-ui.md#daylight-saving-time-dst).

### Alerts

Configure [alerting](https://docs.hightouch.com/syncs/alerting.md) per sync from the **Alerting** tab.

### Sync logs

> [!NOTE]
>
> Warehouse Sync Logs are only available on [Business tier plans](https://hightouch.com/pricing).

Configure [Warehouse Sync Logs](https://docs.hightouch.com/syncs/warehouse-sync-logs.md) from the **Sync logs** tab. This writes the results of your syncs back into your warehouse for more complex analysis.