Sync Modes

Sync modes control how SignalSmith writes data to a destination. Each destination supports an access filter of sync modes depending on its API capabilities.

Available Sync Modes

Upsert

Create or update records. If a matching record exists in the destination (based on the identifier field), it is updated. If no match exists, a new record is created.

• Best for: Keeping destination records in sync with your warehouse without deleting anything
• Identifier required: Yes
• Supported by: Most CRM, marketing, advertising, and warehouse destinations

Insert

Create new records only. Records are always created, regardless of whether a matching record already exists. Duplicates may occur if records already exist in the destination.

• Best for: Event logging, append-only data, streaming destinations
• Identifier required: No
• Supported by: All destinations

Update

Update existing records only. Only records that already exist in the destination (based on the identifier field) are updated. No new records are created.

• Best for: Enriching existing records without creating new ones
• Identifier required: Yes
• Supported by: CRM and warehouse destinations

Mirror

Full synchronization with deletes. The destination is made to exactly match the source model. Records are created, updated, and deleted as needed. Records in the destination that no longer appear in the source model are removed.

• Best for: Keeping a destination table or audience in exact sync with your warehouse
• Identifier required: Yes
• Supported by: Warehouse destinations, advertising platforms, some CRM and cloud storage destinations

Sync Mode Support by Category

Audience Sync Modes

Audience syncs have their own set of modes that control how audience membership is managed in the destination:

Add

Add members only. Users who enter the audience are added to the destination list. Users who leave the audience are not removed.

Remove

Remove members only. Users who leave the audience are removed from the destination list. New audience members are not added.

Mirror

Full membership sync. The destination list is made to exactly match the audience. Members are added and removed as needed to keep the destination in sync.

Upsert

Add members and update attributes. Users who enter the audience are added, and existing members have their attributes updated. Users who leave the audience are not removed.

Choosing a Sync Mode

Consider these factors when choosing a sync mode:

1. Do you need deletes? Use Mirror if the destination should exactly match your source. Use Upsert if you only want to create and update.
2. Is the data append-only? Use Insert for event data, logs, and streaming destinations.
3. Do you want to avoid creating new records? Use Update to enrich existing records only.
4. Is this an audience sync? Use Mirror for full membership sync, Add for growth-only lists, or Remove for suppression lists.

How Sync Modes Work Internally

For Warehouse Destinations

Warehouse syncs use staging tables and SQL operations:

• Insert — INSERT INTO target SELECT * FROM staging
• Upsert — MERGE INTO target USING staging ON key WHEN MATCHED THEN UPDATE WHEN NOT MATCHED THEN INSERT
• Update — MERGE INTO target USING staging ON key WHEN MATCHED THEN UPDATE
• Mirror — MERGE with an additional DELETE for records not in the staging table

For API Destinations

API-based destinations use the platform’s native APIs:

• Insert — POST to the create endpoint
• Upsert — POST to the upsert endpoint (or create-or-update)
• Update — PATCH/PUT to the update endpoint
• Mirror — Upsert + delete records not in the source

For Advertising Destinations

Advertising platforms typically manage audience lists:

• Upsert — Upload user identifiers to the audience list
• Mirror — Replace the entire audience list with the current source data

For Streaming Destinations

Streaming destinations only support Insert mode. Each row from the source model is published as an individual message to the topic, stream, or queue.