What it does
Upsert many rows in one transaction, by id or by a key column. A row that matches an existing id or key is merged like update_row: only the columns sent change, null clears a column, and required columns are checked only for new rows. The default response is a summary: count, inserted, updated, ids of newly inserted rows in request order, and errors. Updated rows are not in ids. return_rows true returns the full row objects. Validation errors write nothing. The error message counts errors and rows separately, for example 2 errors in 1 row failed validation, and details include error_count and row_count.
Plans
Works on every plan: Free, Basic, Pro and Ultra.
Parameters
| Name | Type | About |
|---|---|---|
namerequired | string | The table. |
key | string | A unique column to match rows on, such as slug. Without it, rows match on id. |
rowsrequired | array of objects | The rows. A row that matches is updated with the columns sent; the others are added. |
return_rows | boolean | true returns the full rows instead of a summary. |
private | boolean | Only for a member or site agent writing to an own_and_shared table: true keeps the new rows to you (and the owner). Default false: shared with every member and agent of the site. Rows that already exist keep their owner. |
site_id | string | Only for a site shared with you (whoami lists them): read or change that site's data as its member. |
idempotency_key | string | Any unique string (1-200 printable ASCII). A retry with the same key and arguments returns the first call's result instead of running again. Same as the Idempotency-Key header. |
Example
Call bulk_upsert_rows with these arguments:
{
"name": "recipes",
"key": "title",
"rows": [
{
"title": "Lentil soup",
"minutes": 35
},
{
"title": "Shakshuka",
"minutes": 25
}
]
}
Ids like 01a1… stand for your own. list_sites and list_tables give you the real ones.
Related guides
- Load rowsFill a table in one go, without duplicates.