> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riggery.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# State upsert

> Write keyed JSON records on the Instance.

Writes keyed JSON records. Prefer previous-node JSON `{ collection, items: [{ key, data }] }` for batches. **Collection** / **Key (optional single)** are fallbacks for a single row.

<h2 id="input">
  Input
</h2>

Inspector **Settings**. Empty-field rules for the Graph: [Previous nodes](/graph/previous-nodes). This inspector has no **Insert value**.

On an Agent Tool, both can be **Agent decides** or **Fixed**.

Empty fields do not invent items. No items fails: pass JSON `{ collection, items: [{ key, data }] }` from the previous node, or fill Collection and Key.

| Field                     | Required | Empty | Notes                                                          |
| ------------------------- | -------- | ----- | -------------------------------------------------------------- |
| **Collection**            | No       | —     | Required unless previous Result JSON already has `collection`. |
| **Key (optional single)** | No       | —     | Fallback for one row when the previous Result is not a batch.  |

<h2 id="output">
  Output
</h2>

On the next node, **Previous nodes** lists **`State upsert`: Result** (`{{State upsert.text}}` while the name is unique).

| Output | In menu | Type | Next node gets                                                                                                                                             |
| ------ | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Result | Yes     | Text | A status line such as `Upserted 3 record(s) into "rates".` Not the records. A predicate conflict returns `conflict: …` as Result (the step does not fail). |