Sync Modes

The sync mode determines how SignalSmith handles data at the destination during each sync run. Choosing the right mode depends on your use case, the destination’s capabilities, and whether you need to create, update, or delete records.

Overview

SignalSmith supports three sync modes:

Upsert Mode

Upsert (update + insert) is the most common sync mode. It creates new records in the destination and updates existing ones, but never deletes records.

How It Works

For each row in the model results:

1. SignalSmith looks up the row in the destination using the mapped identifier field(s)
2. If a matching record exists → Update the record with the new attribute values
3. If no matching record exists → Create a new record with all mapped field values

Model Results          Destination (before)         Destination (after)
┌─────┬───────┐       ┌─────┬───────┐             ┌─────┬───────┐
│ id  │ name  │       │ id  │ name  │             │ id  │ name  │
├─────┼───────┤       ├─────┼───────┤             ├─────┼───────┤
│  1  │ Alice │       │  1  │ Alice │  (no change)│  1  │ Alice │
│  2  │ Bob*  │       │  2  │ Bobby │  (updated)  │  2  │ Bob*  │
│  3  │ Carol │       │     │       │  (created)  │  3  │ Carol │
└─────┴───────┘       │  4  │ Dave  │  (kept)     │  4  │ Dave  │
                       └─────┴───────┘             └─────┴───────┘

Note: Dave (id=4) exists in the destination but not in the model results. In upsert mode, Dave is not deleted — the record is simply left untouched.

When to Use Upsert

• CRM syncs — Keep contact records up to date without accidentally deleting contacts
• Data enrichment — Add or update attributes on existing records
• Most production syncs — Upsert is the safest default because it never destroys data

Considerations

• Records removed from the model results will remain in the destination indefinitely
• If you need to remove stale records, use mirror mode instead
• Upsert is idempotent — running the same data multiple times produces the same result

Mirror Mode

Mirror keeps the destination as an exact copy of the model results. It creates new records, updates existing ones, and deletes records that no longer appear in the model results.

How It Works

For each row in the model results:

1. SignalSmith looks up the row in the destination using the mapped identifier field(s)
2. If a matching record exists → Update the record with the new attribute values
3. If no matching record exists → Create a new record

After processing all model rows:

4. For every destination record not in the model results → Delete the record

Model Results          Destination (before)         Destination (after)
┌─────┬───────┐       ┌─────┬───────┐             ┌─────┬───────┐
│ id  │ name  │       │ id  │ name  │             │ id  │ name  │
├─────┼───────┤       ├─────┼───────┤             ├─────┼───────┤
│  1  │ Alice │       │  1  │ Alice │  (no change)│  1  │ Alice │
│  2  │ Bob*  │       │  2  │ Bobby │  (updated)  │  2  │ Bob*  │
│  3  │ Carol │       │     │       │  (created)  │  3  │ Carol │
└─────┴───────┘       │  4  │ Dave  │  (DELETED)  └─────┴───────┘
                       └─────┴───────┘

Dave (id=4) exists in the destination but not in the model results, so it is deleted in mirror mode.

When to Use Mirror

• Audience lists — Ad platform audiences that should exactly match your model (e.g., “Active users in the last 30 days”)
• Segment-based syncs — When the model defines a segment and you want the destination list to match
• Data cleanup — When you need to remove stale records from the destination

Considerations

• Destructive by nature — Mirror mode deletes records. If your model query has a bug that returns fewer rows than expected, legitimate records will be deleted from the destination.
• Use with caution — Start with upsert mode until you’re confident in your model query, then switch to mirror.
• First run behavior — On the first run, SignalSmith has no previous snapshot. All model rows are created, and existing destination records not in the model are deleted.
• Empty model results — If the model query returns zero rows (e.g., due to a warehouse error), mirror mode would delete all records in the destination. SignalSmith includes a safety check that aborts the run if the model returns zero rows in mirror mode.

Safety Features

SignalSmith includes safeguards for mirror mode:

1. Empty result protection — If the model returns zero rows, the sync run is aborted with a warning
2. Delete threshold — If more than 50% of existing records would be deleted, SignalSmith warns you and may require confirmation
3. Deletion preview — Before the first mirror run, you can preview which records would be deleted

Append Mode

Append only creates new records. It never updates or deletes existing records in the destination.

How It Works

For each row in the model results:

1. SignalSmith checks if a record with the same primary key was already synced in a previous run
2. If the primary key is new (not seen in any previous run) → Create a new record
3. If the primary key was already synced → Skip (do nothing)

Run 1 - Model Results     Destination (after run 1)
┌─────┬───────┐           ┌─────┬───────┐
│ id  │ name  │           │ id  │ name  │
├─────┼───────┤           ├─────┼───────┤
│  1  │ Alice │           │  1  │ Alice │  (created)
│  2  │ Bob   │           │  2  │ Bob   │  (created)
└─────┴───────┘           └─────┴───────┘

Run 2 - Model Results     Destination (after run 2)
┌─────┬───────┐           ┌─────┬───────┐
│ id  │ name  │           │ id  │ name  │
├─────┼───────┤           ├─────┼───────┤
│  1  │ Alice*│           │  1  │ Alice │  (skipped, even though name changed)
│  2  │ Bob   │           │  2  │ Bob   │  (skipped)
│  3  │ Carol │           │  3  │ Carol │  (created)
└─────┴───────┘           └─────┴───────┘

Note: Even though Alice’s name changed in run 2, the existing record is not updated. Only Carol (a new primary key) is created.

When to Use Append

• Event data — Send events or activity logs to a destination where you want a complete history
• Audit trails — Maintain a historical record of changes
• Lead import — Import leads once without overwriting subsequent manual edits in the CRM
• One-time loads — Load a batch of records once, then future runs only add new entries

Considerations

• Updates to existing records are never sent — if you need to correct data, use upsert mode
• Append mode tracks which primary keys have been synced to avoid duplicates
• If you change the model query to include previously synced records with different attribute values, those changes are not reflected in the destination

Choosing a Sync Mode

Use this decision tree to choose the right mode:

Do you need to delete records from the destination?
├── Yes → Mirror
└── No
    ├── Do you need to update existing records?
    │   ├── Yes → Upsert
    │   └── No → Append
    └──

Mode Comparison by Use Case

Changing Sync Mode

You can change the sync mode of an existing sync:

1. Navigate to the sync detail page
2. Click Edit
3. Change the sync mode
4. Click Save

Important: Changing from upsert to mirror on the next run will delete destination records not present in the model. Proceed carefully.

Next Steps

• Create a sync and choose a mode
• Map fields for your sync
• Monitor sync runs to verify the mode behavior