Write modes (detailed)
The product has three top-level write_mode options. The SoftRefresh / RewriteFromLast / Dumb policies are not separate modes — they're output_options.append_policy values used with write_mode=append.
The model
Top-level write_mode | What it does | Nested |
|---|---|---|
replace | Fully rewrites the sheet with the run's results | — |
append | Appends / refreshes the tail | append_policy: soft_refresh (default in the wizard), rewrite_from_last, dumb |
append_dedup | Append with key-based dedup (+ incremental date refresh for ads) | dedup key set in output options |
Append policies (only with append)
append_policy | API range | Sheet |
|---|---|---|
soft_refresh | last_sheet_date − 1 … today | refreshes the tail by date, then appends new rows |
rewrite_from_last | last_sheet_date … today | deletes rows from the last date and rewrites them |
dumb | the full requested range | blind physical append (risk of duplicates) |
More detail: Soft refresh, Rewrite from last, Append, AppendDedup, Replace.
1. Replace
A full rewrite of the destination sheet. Old rows are removed; only the latest run's data remains.
- Manual columns to the right of the data matrix — lost
- Empty result — the sheet is cleared (headers usually remain)
- Compatible with scheduling
When: daily "current state" dashboards with no history kept on the same sheet.
2. Append + policies
Plain append on its own just appends. The policy determines the behavior:
soft_refresh (default in the wizard)
Date-aware: takes the last date on the sheet, pulls the API from last−1 through today, refreshes the tail by date, and appends new dates. This is not a key-upsert by Campaign.
rewrite_from_last
From the last sheet date through today: rows from that date are deleted and rewritten. Not a "last row marker" — a date.
dumb
The full API range plus a physical append. Duplicates are possible. Scheduling is not blocked — it's just advanced/risky.
3. AppendDedup
Checks the dedup key(s) before writing. For Meta / Google / TikTok / FB / IG there's also an incremental refresh window (~3 days) on the date field — see AppendDedup.
Choosing a mode
| Scenario | Mode |
|---|---|
| Only the latest snapshot | replace |
| A daily tail with no date duplicates | append + soft_refresh |
| Rewrite from the last date | append + rewrite_from_last |
| A log with no concern for duplicates | append + dumb |
| Unique entities by key | append_dedup |