# Writing JSON Fields

This page explains how ToriiDB sets, increments, and deletes individual fields inside a stored JSON document.

## Writing Fields

```text
SET user.profile.level 2
SET user.profile.active true
SET user.tags.1 database
SET user.meta {"source":"import"}
```

The value text is converted with `utils.Atov`:

| Text | Stored as |
|---|---|
| `null` | JSON null (deletes the field when the parent is an object) |
| `true` / `false` | boolean |
| integer / float | number |
| `{...}` / `[...]` that parses | object / array |
| anything else | string |

| Situation | Result |
|---|---|
| Key missing | A new object is created |
| Key holds non-JSON | Fails: `not JSON type` |
| Key holds a top-level array | Replaced by a new object containing only the written path |
| Intermediate field missing | An empty object is created |
| Intermediate field is a scalar | Fails |
| Array index out of range or not a number | Fails; arrays are never extended |
| `NX` / `XX` | Checked against the top-level key |
| Trailing seconds | Sets expiry; without it an existing expiry stays in memory |
| `VECTOR` | Rejected: `error: VECTOR not supported on field-level SET` |

## Numeric Fields

```text
INCR user.profile.level
INCR user.profile.score 0.5
```

`IncrField` needs a top-level object and an existing numeric field, adds the delta, rewrites the document with `setParsed`, and appends the full document to the log. Missing fields and non-numeric values fail without creating anything.

## Deleting Fields

```text
DEL user.profile.active
```

Only a single dotted argument deletes a field; `DEL a.b c` deletes the top-level keys `a.b` and `c`. `DelField` needs a top-level object. An object field is removed; an array element is set to `null` instead of shrinking the array. Missing intermediate objects on the path are created as empty objects before the delete.

## Related Pages

- [JSON Documents](/json-documents)
- [SET, DEL, INCR](/cli-reference-write)
- [utils](/api-reference-utils)