Upsert Rows
The Upsert Rows stage inserts a new row, or if it already exists (based on a unique column), updates that row instead. This is useful for syncing data when you don't know if a record exists.
Overview
Input Parameters
| Parameter | Variable | Required | Description |
| Table Name | {{tableName}} | Yes | The name of the table to upsert into |
| Body Payload | {{bodyPayload}} | Yes | JSON string containing the row data |
| On Conflict | {{onConflict}} | Yes | Unique column(s) to check for existing rows |
How It Works
| If Row with Conflict Column Value... | Action |
| Does NOT exist | INSERT new row |
| Already exists | UPDATE existing row |
On Conflict Options
Single Column:
Multiple Columns (Composite Key):
warehouse_id,product_id
Important: The column(s) specified in onConflict must have a unique constraint in your Supabase table.
Output
| Output | Variable | Description |
| Upserted Rows | {{upsertedRows}} | Array containing the inserted or updated row |
| Success | {{success}} | Boolean indicating if the operation succeeded |
Usage Examples
Example 1: Upsert with Single Unique Column
| Parameter | Value |
| tableName | users |
| bodyPayload | "{\"email\": \"[email protected]\", \"name\": \"John Doe\", \"status\": \"active\"}" |
| onConflict |
Example 2: Upsert with Composite Key
| Parameter | Value |
| tableName | inventory |
| bodyPayload | "{\"warehouse_id\": 1, \"product_id\": 100, \"quantity\": 50}" |
| onConflict | warehouse_id,product_id |
Example 3: Sync External Data
| Parameter | Value |
| tableName | products |
| bodyPayload | "{\"sku\": \"ABC-123\", \"name\": \"Widget\", \"price\": 29.99, \"stock\": 100}" |
| onConflict | sku |
When to Use Upsert vs Insert vs Update
| Scenario | Use | Why |
| User registration | Insert | Should error if email exists |
| Edit user profile | Update | User must exist |
| Sync from external API | Upsert | Don't know if record exists |
| Import CSV data | Upsert | Avoid duplicates automatically |
| Track daily stats | Upsert | Create first time, update after |