Book a demo

Add or Update Records

grist.upsert_records
ActionDatabases & warehousesconnection required

Calls the Grist API with the connection's credentials.

Add rows or update the ones already matching, using a 'require' matcher per record instead of a row id.

Ask about GristAll Grist nodesProvider API docs ↗

Connection

Required
Yes — the node will not save without one
Auth type
API key
Providers
Grist
Secret shape
the API key, or {"api_key": "…"}
Config it needs
base_url, doc_id
Resolved by
config.connection_id, else node.connection_id

Configuration

6 fields, 2 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

FieldTypeRequiredDefaultConstraintsExample
table_id
The table to act on, as its table id (the TABLE ID shown in Raw Data).
stringYes——People
records
Rows to add or update. Each entry needs a 'require' object naming the columns to match on, plus a 'fields' object to write.
arrayYes—≥ 1 characters; array of object[{"fields":{"Age":37},"require":{"Name":"Ada"}}]
doc_id
Document to act in; overrides the document set on the connection.
stringNo——mR9tqLGSKB2Z
onmany
Which rows to update when a record's matcher hits more than one.
stringNofirstone of "first", "none", "all"—
noadd
Update matching rows only, and never add a row that does not exist yet.
booleanNofalse——
noupdate
Add missing rows only, and leave rows that already match untouched.
booleanNofalse——

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "doc_id": "mR9tqLGSKB2Z",
  "noadd": false,
  "noupdate": false,
  "onmany": "first",
  "records": [
    {
      "fields": {
        "Age": 37
      },
      "require": {
        "Name": "Ada"
      }
    }
  ],
  "table_id": "People"
}

Output

One shape.

result

FieldTypeExample
upserted
How many records were sent for add-or-update.
number—
table_id
The table id the call acted on.
string—
doc_id
The Grist document the call acted on.
string—
{
  "doc_id": "",
  "table_id": "",
  "upserted": 0
}

Related Grist nodes

See Add or Update Records run in a workflow.

In a technical demo we add the Grist connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demoTalk to sales